July 2024

Software Development Kit

DeckLink
SDK Manual

macOS™

DeckLink SDK Manual

Windows™
Contents

Linux™

1

Contents
Introduction

14

Welcome

14

Overview

14

Section 1 — API Design

15

1.1

API Design

15

1.1.1

Supported Products

15

1.1.2

Supported Operating Systems

15

1.1.3

3rd Party Product and Feature Support

15

1.1.3.1

NVIDIA GPUDirect support

15

1.1.3.2

AMD DirectGMA support

15

1.1.4

Object Interfaces

15

1.1.5

Reference Counting

16

1.1.6

Interface Stability16

1.1.6.1

New Interfaces

16

1.1.6.2

Updated Interfaces

16

1.1.6.3

Deprecated Interfaces

16

1.1.6.4

Removed Interfaces

16

1.2

Interface Reference

17

1.2.1

IUnknown Interface 17

1.2.1.1

IUnknown::QueryInterface method

17

1.2.1.2

IUnknown::AddRef method

18

1.2.1.3

IUnknown::Release method 

18Section 2 — DeckLink API

19

2.1

Using the DeckLink API in a project

19

2.2

Sandboxing support on macOS

19

2.3

Accessing DeckLink devices

19

2.3.1

Windows

20

2.3.2

macOS and Linux

20

2.4

High level interface

20

2.4.1

Capture

20

2.4.2

Playback

21

2.4.3

3D Functionality21

2.4.3.1

3D Capture

21

2.4.3.2

3D Playback

22

2.4.4

DeckLink Device Notification

23

2.4.5

Streaming Encoder

23

2.4.5.1

Streaming Encoder Capture

23

2.4.6

Automatic Mode Detection

24

2.4.7

Ancillary Data functionality24

2.4.7.1

VANC Capture

24

2.4.7.2

VANC Output

25

2.4.8

Keying26

Contents2

2.4.9Timecode/Timecode user bits

26

2.4.9.1

Timecode Capture

26

2.4.9.2

Timecode Output

27

2.4.10H.265 Capture

27

2.4.10.1

Encoded Capture

28

2.4.11

Device Profiles

28

2.4.11.1

Determine the current profile ID

30

2.4.11.2

List the available profiles

30

2.4.11.3

Select a new profile30

2.4.11.4

Handle a profile change notification

31

2.4.12HDR Metadata31

2.4.12.1

CEA/SMPTE Static HDR Capture31

2.4.12.2

CEA/SMPTE Static HDR Playback

32

2.4.12.3

Dolby Vision® Playback

32

2.4.13

Synchronized Capture/Playback

34

2.4.13.1

Synchronized Capture

34

2.4.13.2

Synchronized Playback

34

2.4.14

Video Frame Conversion

35

2.5

Interface Reference

35

2.5.1

IDeckLinkIterator Interface35

2.5.1.1

IDeckLinkIterator::Next method

36

2.5.2

IDeckLink Interface36

2.5.2.1

IDeckLink::GetModelName method

37

2.5.2.2

IDeckLink::GetDisplayName method

37

2.5.3

IDeckLinkOutput interface37

2.5.3.1

IDeckLinkOutput::DoesSupportVideoMode method

39

2.5.3.2

IDeckLinkOutput::GetDisplayMode method

40

2.5.3.3

IDeckLinkOutput::IsScheduledPlaybackRunning method

40

2.5.3.4

IDeckLinkOutput::GetDisplayModeIterator method

41

2.5.3.5

IDeckLinkOutput::SetScreenPreviewCallback method

41

2.5.3.6

IDeckLinkOutput::EnableVideoOutput method

42

2.5.3.7

IDeckLinkOutput::DisableVideoOutput method

42

2.5.3.8

IDeckLinkOutput::SetVideoOutputFrameMemoryAllocator method

43

2.5.3.9

IDeckLinkOutput::CreateVideoFrame method

43

2.5.3.10

IDeckLinkOutput::CreateAncillaryData method

44

2.5.3.11

IDeckLinkOutput::DisplayVideoFrameSync method

44

2.5.3.12

IDeckLinkOutput::ScheduleVideoFrame method

45

2.5.3.13

IDeckLinkOutput::SetScheduledFrameCompletionCallback method

45

2.5.3.14

IDeckLinkOutput::GetBufferedVideoFrameCount method

46

2.5.3.15

IDeckLinkOutput::EnableAudioOutput method

46

2.5.3.16

IDeckLinkOutput::DisableAudioOutput method

47

2.5.3.17

IDeckLinkOutput::WriteAudioSamplesSync method

47

2.5.3.18

IDeckLinkOutput::BeginAudioPreroll method

48

2.5.3.19

IDeckLinkOutput::EndAudioPreroll method

48

2.5.3.20

IDeckLinkOutput::ScheduleAudioSamples method

49

Contents3

2.5.3.21

IDeckLinkOutput::GetBufferedAudioSampleFrameCount method

50

2.5.3.22

IDeckLinkOutput::FlushBufferedAudioSamples method

50

2.5.3.23

IDeckLinkOutput::SetAudioCallback method

51

2.5.3.24

IDeckLinkOutput::StartScheduledPlayback method

51

2.5.3.25

IDeckLinkOutput::StopScheduledPlayback method

52

2.5.3.26

IDeckLinkOutput::GetScheduledStreamTime method

52

2.5.3.27

IDeckLinkOutput::GetReferenceStatus method

53

2.5.3.28

IDeckLinkOutput::GetHardwareReferenceClock method

53

2.5.3.29

IDeckLinkOutput::GetFrameCompletionReferenceTimestamp method

54

2.5.4

IDeckLinkInput Interface54

2.5.4.1

IDeckLinkInput::DoesSupportVideoMode method

56

2.5.4.2

IDeckLinkInput::GetDisplayMode method

57

2.5.4.3

IDeckLinkInput::GetDisplayModeIterator method

57

2.5.4.4

IDeckLinkInput::SetScreenPreviewCallback method

58

2.5.4.5

IDeckLinkInput::EnableVideoInput method

58

2.5.4.6

IDeckLinkInput::GetAvailableVideoFrameCount method

59

2.5.4.7

IDeckLinkInput::DisableVideoInput method

59

2.5.4.8

IDeckLinkInput::EnableAudioInput method

59

2.5.4.9

IDeckLinkInput::DisableAudioInput method

60

2.5.4.10

IDeckLinkInput::GetAvailableAudioSampleFrameCount method

60

2.5.4.11

IDeckLinkInput::SetVideoInputFrameMemoryAllocator method

61

2.5.4.12

IDeckLinkInput::StartStreams method

61

2.5.4.13

IDeckLinkInput::StopStreams method

62

2.5.4.14

IDeckLinkInput::FlushStreams method

62

2.5.4.15

IDeckLinkInput::PauseStreams method

62

2.5.4.16

IDeckLinkInput::SetCallback method

63

2.5.4.17

IDeckLinkInput::GetHardwareReferenceClock method

63

2.5.5

IDeckLinkVideoFrame Interface64

2.5.5.1

IDeckLinkVideoFrame::GetWidth method

65

2.5.5.2

IDeckLinkVideoFrame::GetHeight method

65

2.5.5.3

IDeckLinkVideoFrame::GetRowBytes method

66

2.5.5.4

IDeckLinkVideoFrame::GetPixelFormat method

66

2.5.5.5

IDeckLinkVideoFrame::GetFlags method

66

2.5.5.6

IDeckLinkVideoFrame::GetBytes method

66

2.5.5.7

IDeckLinkVideoFrame::GetTimecode method

67

2.5.5.8

IDeckLinkVideoFrame::GetAncillaryData method

67

2.5.6

IDeckLinkVideoOutputCallback Interface67

2.5.6.1

IDeckLinkVideoOutputCallback::ScheduledFrameCompleted method

68

2.5.6.2

IDeckLinkVideoOutputCallback::ScheduledPlaybackHasStopped method

68

2.5.7

IDeckLinkMutableVideoFrame Interface69

2.5.7.1

IDeckLinkMutableVideoFrame::SetFlags method

69

2.5.7.2

IDeckLinkMutableVideoFrame::SetTimecode method

70

2.5.7.3

IDeckLinkMutableVideoFrame::SetTimecodeFromComponents method

70

2.5.7.4

IDeckLinkMutableVideoFrame::SetAncillaryData method

71

2.5.7.5

IDeckLinkMutableVideoFrame::SetTimecodeUserBits method

71

Contents42.5.8

IDeckLinkVideoFrame3DExtensions Interface72

2.5.8.1

IDeckLinkVideoFrame3DExtensions::Get3DPackingFormat method

72

2.5.8.2

IDeckLinkVideoFrame3DExtensions::GetFrameForRightEye method

73

2.5.9

IDeckLinkAudioOutputCallback Interface73

2.5.9.1

IDeckLinkAudioOutputCallback::RenderAudioSamples method

74

2.5.10

IDeckLinkInputCallback Interface74

2.5.10.1

IDeckLinkInputCallback::VideoInputFrameArrived method

75

2.5.10.2

IDeckLinkInputCallback::VideoInputFormatChanged method

76

2.5.11

IDeckLinkVideoInputFrame Interface76

2.5.11.1

IDeckLinkVideoInputFrame::GetStreamTime method

77

2.5.11.2

IDeckLinkVideoInputFrame::GetHardwareReferenceTimestamp method

77

2.5.12

IDeckLinkAudioInputPacket Interface78

2.5.12.1

IDeckLinkAudioInputPacket::GetSampleFrameCount method

78

2.5.12.2

IDeckLinkAudioInputPacket::GetBytes method

78

2.5.12.3

IDeckLinkAudioInputPacket::GetPacketTime method

79

2.5.13

IDeckLinkDisplayModeIterator Interface79

2.5.13.1

IDeckLinkDisplayModeIterator::Next method

80

2.5.14

IDeckLinkDisplayMode Interface80

2.5.14.1

IDeckLinkDisplayMode::GetWidth method

81

2.5.14.2

IDeckLinkDisplayMode::GetHeight method

81

2.5.14.3

IDeckLinkDisplayMode::GetName method

81

2.5.14.4

IDeckLinkDisplayMode::GetDisplayMode method

82

2.5.14.5

IDeckLinkDisplayMode::GetFrameRate method

82

2.5.14.6

IDeckLinkDisplayMode::GetFieldDominance method

82

2.5.14.7

IDeckLinkDisplayMode::GetFlags method

83

2.5.15

IDeckLinkConfiguration Interface83

2.5.15.1

IDeckLinkConfiguration::SetFlag method

84

2.5.15.2

IDeckLinkConfiguration::GetFlag method

84

2.5.15.3

IDeckLinkConfiguration::SetInt method

85

2.5.15.4

IDeckLinkConfiguration::GetInt method

85

2.5.15.5

IDeckLinkConfiguration::SetFloat method

86

2.5.15.6

IDeckLinkConfiguration::GetFloat method

86

2.5.15.7

IDeckLinkConfiguration::SetString method

87

2.5.15.8

IDeckLinkConfiguration::GetString method

87

2.5.15.9

IDeckLinkConfiguration::WriteConfigurationToPreferences method

88

2.5.16

IDeckLinkAPIInformation Interface88

2.5.16.1

IDeckLinkAPIInformation::GetFlag method

89

2.5.16.2

IDeckLinkAPIInformation::GetInt method

89

2.5.16.3

IDeckLinkAPIInformation::GetFloat method

90

2.5.16.4

IDeckLinkAPIInformation::GetString method

90

2.5.17

IDeckLinkProfileAttributes Interface91

2.5.17.1

IDeckLinkProfileAttributes::GetFlag method

91

2.5.17.2

IDeckLinkProfileAttributes::GetInt method

92

2.5.17.3

IDeckLinkProfileAttributes::GetFloat method

92

2.5.17.4

IDeckLinkProfileAttributes::GetString method

93

Contents5

2.5.18

IDeckLinkMemoryAllocator Interface93

2.5.18.1

IDeckLinkMemoryAllocator::AllocateBuffer method

94

2.5.18.2

IDeckLinkMemoryAllocator::ReleaseBuffer method

94

2.5.18.3

IDeckLinkMemoryAllocator::Commit method

95

2.5.18.4

IDeckLinkMemoryAllocator::Decommit method

95

2.5.19IDeckLinkKeyer Interface 96

2.5.19.1

IDeckLinkKeyer::Enable method

96

2.5.19.2

IDeckLinkKeyer::SetLevel method

97

2.5.19.3

IDeckLinkKeyer::RampUp method

98

2.5.19.4

IDeckLinkKeyer::RampDown method

98

2.5.19.5

IDeckLinkKeyer::Disable method

98

2.5.20

IDeckLinkVideoFrameAncillary Interface99

2.5.20.1

IDeckLinkVideoFrameAncillary::GetPixelFormat method

99

2.5.20.2

IDeckLinkVideoFrameAncillary::GetDisplayMode method

100

2.5.20.3

IDeckLinkVideoFrameAncillary::GetBufferForVerticalBlankingLine method

100

2.5.21

IDeckLinkVideoFrameAncillaryPackets Interface 101

2.5.21.1

IDeckLinkVideoFrameAncillaryPackets::GetPacketIterator method 101

2.5.21.2

IDeckLinkVideoFrameAncillaryPackets::GetFirstPacketByID method 102

2.5.21.3

IDeckLinkVideoFrameAncillaryPackets::AttachPacket method 102

2.5.21.4

IDeckLinkVideoFrameAncillaryPackets::DetachPacket method 103

2.5.21.5

IDeckLinkVideoFrameAncillaryPackets::DetachAllPackets method 103

2.5.22

IDeckLinkAncillaryPacketIterator Interface 103

2.5.22.1

IDeckLinkAncillaryPacketIterator::Next method 

104

2.5.23

IDeckLinkAncillaryPacket Interface 104

2.5.23.1

IDeckLinkAncillaryPacket::GetBytes method 

105

2.5.23.2

IDeckLinkAncillaryPacket::GetDID method 

105

2.5.23.3

IDeckLinkAncillaryPacket::GetSDID method 

105

2.5.23.4

IDeckLinkAncillaryPacket::GetLineNumber method 

106

2.5.23.5

IDeckLinkAncillaryPacket::GetDataStreamIndex method 

106

2.5.24

IDeckLinkTimecode Interface106

2.5.24.1

IDeckLinkTimecode::GetBCD method

107

2.5.24.2

IDeckLinkTimecode::GetComponents method

107

2.5.24.3

IDeckLinkTimecode::GetString method

108

2.5.24.4

IDeckLinkTimecode::GetFlags method

108

2.5.24.5

IDeckLinkTimecode::GetTimecodeUserBits method

108

2.5.25

IDeckLinkScreenPreviewCallback Interface109

2.5.25.1

IDeckLinkScreenPreviewCallback::DrawFrame method

109

2.5.26

IDeckLinkGLScreenPreviewHelper Interface110

2.5.26.1

IDeckLinkGLScreenPreviewHelper::InitializeGL method

111

2.5.26.2

IDeckLinkGLScreenPreviewHelper::PaintGL method

111

2.5.26.3

IDeckLinkGLScreenPreviewHelper::SetFrame method

111

2.5.26.4

IDeckLinkGLScreenPreviewHelper::Set3DPreviewFormat

112

2.5.27

IDeckLinkCocoaScreenPreviewCallback Interface112

2.5.28

IDeckLinkDX9ScreenPreviewHelper Interface113

2.5.28.1

IDeckLinkDX9ScreenPreviewHelper::Initialize method

114

Contents

6

2.5.28.2

IDeckLinkDX9ScreenPreviewHelper::Render method

114

2.5.28.3

IDeckLinkDX9ScreenPreviewHelper::SetFrame method

114

2.5.28.4

IDeckLinkDX9ScreenPreviewHelper::Set3DPreviewFormat method

115

2.5.29IDeckLinkDeckControl Interface115

2.5.29.1

IDeckLinkDeckControl::Open method

117

2.5.29.2

IDeckLinkDeckControl::Close method

117

2.5.29.3

IDeckLinkDeckControl::GetCurrentState method

118

2.5.29.4

IDeckLinkDeckControl::SetStandby method

118

2.5.29.5

IDeckLinkDeckControl::SendCommand method

119

2.5.29.6

IDeckLinkDeckControl::Play method

119

2.5.29.7

IDeckLinkDeckControl::Stop method

120

2.5.29.8

IDeckLinkDeckControl::TogglePlayStop method

120

2.5.29.9

IDeckLinkDeckControl::Eject method

121

2.5.29.10

IDeckLinkDeckControl::GoToTimecode method

121

2.5.29.11

IDeckLinkDeckControl::FastForward method

122

2.5.29.12

IDeckLinkDeckControl::Rewind method

122

2.5.29.13

IDeckLinkDeckControl::StepForward method

123

2.5.29.14

IDeckLinkDeckControl::StepBack method

123

2.5.29.15

IDeckLinkDeckControl::Jog method

124

2.5.29.16

IDeckLinkDeckControl::Shuttle method

124

2.5.29.17

IDeckLinkDeckControl::GetTimecodeString method

125

2.5.29.18

IDeckLinkDeckControl::GetTimecode method

125

2.5.29.19

IDeckLinkDeckControl::GetTimecodeBCD method

125

2.5.29.20

IDeckLinkDeckControl::SetPreroll method

126

2.5.29.21

IDeckLinkDeckControl::GetPreroll method

126

2.5.29.22

IDeckLinkDeckControl::SetCaptureOffset method

127

2.5.29.23

IDeckLinkDeckControl::GetCaptureOffset method

127

2.5.29.24

IDeckLinkDeckControl::SetExportOffset method

127

2.5.29.25

IDeckLinkDeckControl::GetExportOffset method

128

2.5.29.26

IDeckLinkDeckControl::GetManualExportOffset method

128

2.5.29.27

IDeckLinkDeckControl::StartExport method

129

2.5.29.28

IDeckLinkDeckControl::StartCapture method

130

2.5.29.29

IDeckLinkDeckControl::GetDeviceID method

131

2.5.29.30

IDeckLinkDeckControl::Abort method

131

2.5.29.31

IDeckLinkDeckControl::CrashRecordStart method

131

2.5.29.32

IDeckLinkDeckControl::CrashRecordStop method

132

2.5.29.33

IDeckLinkDeckControl::SetCallback method

132

2.5.30

IDeckLinkDeckControlStatusCallback Interface

133

2.5.30.1

IDeckLinkDeckControlStatusCallback::TimecodeUpdate method

133

2.5.30.2

IDeckLinkDeckControlStatusCallback::VTRControlStateChanged method

134

2.5.30.3

IDeckLinkDeckControlStatusCallback::DeckControlEventReceived method

134

2.5.30.4

IDeckLinkDeckControlStatusCallback::DeckControlStatusChanged method

135

2.5.31

IDeckLinkDiscovery Interface135

2.5.31.1

IDeckLinkDiscovery::InstallDeviceNotifications method

136

2.5.31.2

IDeckLinkDiscovery:: UninstallDeviceNotifications method

136

Contents

7

2.5.32

IDeckLinkDeviceNotificationCallback

136

2.5.32.1

IDeckLinkDeviceNotificationCallback::DeckLinkDeviceArrived method

137

2.5.32.2

IDeckLinkDeviceNotificationCallback::DeckLinkDeviceRemoved method

137

2.5.33

IDeckLinkNotification Interface

138

2.5.33.1

IDeckLinkNotification::Subscribe method

138

2.5.33.2

IDeckLinkNotification::Unsubscribe method

139

2.5.34

IDeckLinkNotificationCallback Interface139

2.5.34.1

IDeckLinkNotificationCallback::Notify method

140

2.5.35

IDeckLinkEncoderInput Interface140

2.5.35.1

IDeckLinkEncoderInput::DoesSupportVideoMode method 

141

2.5.35.2

IDeckLinkEncoderInput::GetDisplayMode method

142

2.5.35.3

IDeckLinkEncoderInput::GetDisplayModeIterator

142

2.5.35.4

IDeckLinkEncoderInput::EnableVideoInput

143

2.5.35.5

IDeckLinkEncoderInput::DisableVideoInput

143

2.5.35.6

IDeckLinkEncoderInput::EnableAudioInput

144

2.5.35.7

IDeckLinkEncoderInput::DisableAudioInput

144

2.5.35.8

IDeckLinkEncoderInput::StartStreams

145

2.5.35.9

IDeckLinkEncoderInput::StopStreams

145

2.5.35.10

IDeckLinkEncoderInput::PauseStreams

145

2.5.35.11

IDeckLinkEncoderInput::FlushStreams

146

2.5.35.12

IDeckLinkEncoderInput::SetCallback

146

2.5.35.13

IDeckLinkEncoderInput::GetHardwareReferenceClock

147

2.5.35.14

IDeckLinkEncoderInput::SetMemoryAllocator

147

2.5.35.15

IDeckLinkEncoderInput::GetAvailableAudioSampleFrameCount148

2.5.35.16

IDeckLinkEncoderInput::GetAvailablePacketsCount method

148

2.5.36

IDeckLinkEncoderInputCallback Interface149

2.5.36.1

IDeckLinkEncoderInputCallback::VideoInputSignalChanged method

149

2.5.36.2

IDeckLinkEncoderInputCallback::VideoPacketArrived

150

2.5.36.3

IDeckLinkEncoderInputCallback::AudioPacketArrived

150

2.5.37

IDeckLinkEncoderPacket Interface151

2.5.37.1

IDeckLinkEncoderPacket::GetBytes method

151

2.5.37.2

IDeckLinkEncoderPacket::GetSize method

151

2.5.37.3

IDeckLinkEncoderPacket::GetStreamTime method

152

2.5.37.4

IDeckLinkEncoderPacket::GetPacketType method

152

2.5.38

IDeckLinkEncoderVideoPacket Interface152

2.5.38.1

IDeckLinkEncoderVideoPacket::GetPixelFormat method

153

2.5.38.2

IDeckLinkEncoderVideoPacket::GetHardwareReferenceTimestamp method

153

2.5.38.3

IDeckLinkEncoderVideoPacket::GetTimecode method

154

2.5.39IDeckLinkEncoderAudioPacket Interface154

2.5.39.1

IDeckLinkEncoderAudioPacket::GetAudioFormat method

155

2.5.40

IDeckLinkH265NALPacket Interface155

2.5.40.1

IDeckLinkH265NALPacket::GetUnitType method

155

2.5.40.2

IDeckLinkH265NALPacket::GetBytesNoPrefix method

156

2.5.40.3

IDeckLinkH265NALPacket::GetSizeNoPrefix method

156

2.5.41

IDeckLinkEncoderConfiguration Interface

156

Contents

8

2.5.41.1

IDeckLinkEncoderConfiguration::SetFlag method

157

2.5.41.2

IDeckLinkEncoderConfiguration::GetFlag method

157

2.5.41.3

IDeckLinkEncoderConfiguration::SetInt method

158

2.5.41.4

IDeckLinkEncoderConfiguration::GetInt method

158

2.5.41.5

IDeckLinkEncoderConfiguration::SetFloat method

159

2.5.41.6

IDeckLinkEncoderConfiguration::GetFloat method

159

2.5.41.7

IDeckLinkEncoderConfiguration::SetString method

160

2.5.41.8

IDeckLinkEncoderConfiguration::GetString method

160

2.5.41.9

IDeckLinkEncoderConfiguration::GetBytes method

161

2.5.42

IDeckLinkStatus Interface161

2.5.42.1

IDeckLinkStatus::GetFlag method 

162

2.5.42.2

IDeckLinkStatus::GetInt method

162

2.5.42.3

IDeckLinkStatus::GetFloat method

163

2.5.42.4

IDeckLinkStatus::GetString method

163

2.5.42.5

IDeckLinkStatus::GetBytes method

164

2.5.43

IDeckLinkVideoFrameMetadataExtensions Interface164

2.5.43.1

IDeckLinkVideoFrameMetadataExtensions::GetInt method

165

2.5.43.2

IDeckLinkVideoFrameMetadataExtensions::GetFloat method

165

2.5.43.3

IDeckLinkVideoFrameMetadataExtensions::GetFlag method

166

2.5.43.4

IDeckLinkVideoFrameMetadataExtensions::GetString method

166

2.5.43.5

IDeckLinkVideoFrameMetadataExtensions::GetBytes method

167

2.5.44

IDeckLinkVideoConversion Interface167

2.5.44.1

IDeckLinkVideoConversion::ConvertFrame method

168

2.5.45

IDeckLinkHDMIInputEDID Interface 168

2.5.45.1

IDeckLinkHDMIInputEDID::SetInt method 

169

2.5.45.2

IDeckLinkHDMIInputEDID::GetInt method

169

2.5.45.3

IDeckLinkHDMIInputEDID::WriteToEDID method

170

2.5.46

IDeckLinkProfileManager Interface170

2.5.46.1

IDeckLinkProfileManager::GetProfiles method

171

2.5.46.2

IDeckLinkProfileManager::GetProfile method

171

2.5.46.3

IDeckLinkProfileManager::SetCallback method 

172

2.5.47

IDeckLinkProfileIterator Interface172

2.5.47.1

IDeckLinkProfileIterator::Next method

173

2.5.48

IDeckLinkProfile Interface

173

2.5.48.1

IDeckLinkProfile::GetDevice method

174

2.5.48.2

IDeckLinkProfile::IsActive method 

174

2.5.48.3

IDeckLinkProfile::SetActive method

175

2.5.48.4

IDeckLinkProfile::GetPeers method 

175

2.5.49IDeckLinkProfileCallback Interface175

2.5.49.1

IDeckLinkProfileCallback::ProfileChanging method

176

2.5.49.2

IDeckLinkProfileCallback::ProfileActivated method

177

2.5.50

IDeckLinkMetalScreenPreviewHelper Interface177

2.5.50.1

IDeckLinkMetalScreenPreviewHelper::Initialize method

178

2.5.50.2

IDeckLinkMetalScreenPreviewHelper::Draw method

179

2.5.50.3

IDeckLinkMetalScreenPreviewHelper::SetFrame method

180

Contents

92.5.50.4

IDeckLinkMetalScreenPreviewHelper::Set3DPreviewFormat method

180

2.5.51

IDeckLinkWPFDX9ScreenPreviewHelper Interface181

2.5.51.1

IDeckLinkWPFDX9ScreenPreviewHelper::Initialize method

181

2.5.51.2

IDeckLinkWPFDX9ScreenPreviewHelper::Render method

182

2.5.51.3

IDeckLinkWPFDX9ScreenPreviewHelper::SetSurfaceSize method

182

2.5.51.4

IDeckLinkWPFDX9ScreenPreviewHelper::SetFrame method

183

2.5.51.5

IDeckLinkWPFDX9ScreenPreviewHelper::Set3DPreviewFormat method

183

2.5.51.6

IDeckLinkWPFDX9ScreenPreviewHelper::GetBackBuffer method

184

2.6

Streaming Interface Reference

184

2.6.1

IBMDStreamingDiscovery Interface184

2.6.1.1

IBMDStreamingDiscovery::InstallDeviceNotifications method

185

2.6.1.2

IBMDStreamingDiscovery::UninstallDeviceNotifications method

185

2.6.2

IBMDStreamingDeviceNotificationCallback Interface185

2.6.2.1

IBMDStreamingDeviceNotificationCallback::StreamingDeviceArrived method

186

2.6.2.2

IBMDStreamingDeviceNotificationCallback::StreamingDeviceRemoved method

186

2.6.2.3

IBMDStreamingDeviceNotificationCallback::StreamingDeviceModeChanged method

187

2.6.3

IBMDStreamingVideoEncodingMode Interface187

2.6.3.1

IBMDStreamingVideoEncodingMode::GetName method

188

2.6.3.2

IBMDStreamingVideoEncodingMode::GetPresetID method

188

2.6.3.3

IBMDStreamingVideoEncodingMode::GetSourcePositionX method

189

2.6.3.4

IBMDStreamingVideoEncodingMode::GetSourcePositionY method

189

2.6.3.5

IBMDStreamingVideoEncodingMode::GetSourceWidth method

189

2.6.3.6

IBMDStreamingVideoEncodingMode::GetSourceHeight method

189

2.6.3.7

IBMDStreamingVideoEncodingMode::GetDestWidth method

190

2.6.3.8

IBMDStreamingVideoEncodingMode::GetDestHeight method

190

2.6.3.9

IBMDStreamingVideoEncodingMode::GetFlag method

190

2.6.3.10

IBMDStreamingVideoEncodingMode::GetInt method

191

2.6.3.11

IBMDStreamingVideoEncodingMode::GetFloat method 

191

2.6.3.12

IBMDStreamingVideoEncodingMode::GetString method 

192

2.6.3.13

IBMDStreamingVideoEncodingMode::CreateMutableVideoEncodingMode method 

192

2.6.4

IBMDStreamingMutableVideoEncodingMode Interface193

2.6.4.1

IBMDStreamingMutableVideoEncodingMode::SetSourceRect method 

193

2.6.4.2

IBMDStreamingMutableVideoEncodingMode::SetDestSize method 

194

2.6.4.3

IBMDStreamingMutableVideoEncodingMode::SetFlag method 

194

2.6.4.4

IBMDStreamingMutableVideoEncodingMode::SetInt method 

195

2.6.4.5

IBMDStreamingMutableVideoEncodingMode::SetFloat method 

195

2.6.4.6

IBMDStreamingMutableVideoEncodingMode::SetString method 

196

2.6.5

IBMDStreamingVideoEncodingMode::PresetIteratorInterface 

196

2.6.5.1

IBMDStreamingVideoEncodingModePresetIterator::Next method 

197

2.6.6

IBMDStreamingDeviceInput Interface 

197

2.6.6.1

IBMDStreamingDeviceInput::DoesSupportVideoInputMode method 

198

2.6.6.2

IBMDStreamingDeviceInput::GetVideoInputModeIterator method 

198

2.6.6.3

IBMDStreamingDeviceInput::SetVideoInputMode method

199

2.6.6.4

IBMDStreamingDeviceInput::GetCurrentDetectedVideoInputMode method

199

2.6.6.5

IBMDStreamingDeviceInput::GetVideoEncodingMode method200

Contents

10

2.6.6.6

IBMDStreamingDeviceInput::GetVideoEncodingModePresetIterator method

200

2.6.6.7

IBMDStreamingDeviceInput::DoesSupportVideoEncodingMode method

201

2.6.6.8

IBMDStreamingDeviceInput::SetVideoEncodingMode method

201

2.6.6.9

IBMDStreamingDeviceInput::StartCapture method

202

2.6.6.10

IBMDStreamingDeviceInput::StopCapture method

202

2.6.6.11

IBMDStreamingDeviceInput::SetCallback method

202

2.6.7

IBMDStreamingH264InputCallback Interface203

2.6.7.1

IBMDStreamingH264InputCallback::H264NALPacketArrived method

203

2.6.7.2

IBMDStreamingH264InputCallback::H264AudioPacketArrived method

204

2.6.7.3

IBMDStreamingH264InputCallback::MPEG2TSPacketArrived method 

2042.6.7.4

IBMDStreamingH264InputCallback::H264VideoInputConnectorScanning
Changed method

205

2.6.7.5

IBMDStreamingH264InputCallback::H264VideoInputConnectorChanged
method205

2.6.7.6

IBMDStreamingH264InputCallback::H264VideoInputModeChanged method

206

2.6.8

IBMDStreamingH264NALPacket Interface206

2.6.8.1

IBMDStreamingH264NALPacket::GetPayloadSize method

207

2.6.8.2

IBMDStreamingH264NALPacket::GetBytes method

207

2.6.8.3

IBMDStreamingH264NALPacket::GetBytesWithSizePrefix method

207

2.6.8.4

IBMDStreamingH264NALPacket::GetDisplayTime method

208

2.6.9

IBMDStreamingAudioPacket Interface208

2.6.9.1

IBMDStreamingAudioPacket::GetCodec method

209

2.6.9.2

IBMDStreamingAudioPacket::GetPayloadSize method

209

2.6.9.3

IBMDStreamingAudioPacket::GetBytes method

209

2.6.9.4

IBMDStreamingAudioPacket::GetPlayTime method

210

2.6.10IBMDStreamingMPEG2TSPacket Interface210

2.6.10.1

IBMDStreamingMPEG2TSPacket::GetPayloadSize method

211

2.6.10.2

IBMDStreamingMPEG2TSPacket::GetBytes method

211

2.6.11IBMDStreamingH264NALParser Interface211

2.6.11.1

IBMDStreamingH264NALParser::IsNALSequenceParameterSet method

212

2.6.11.2

IBMDStreamingH264NALParser::IsNALPictureParameterSet method

212

2.6.11.3

IBMDStreamingH264NALParser::GetProfileAndLevelFromSPS method

213

Section 3 — Common Data Types

214

3.1

Basic Types

214

3.2

Time Representation

215

3.3

Display Modes

216

3.4

Pixel Formats

220

3.5

Field Dominance

227

3.6

Frame Flags

228

3.7

Video Input Flags

228

3.8

Video Output Flags

228

3.9

Output Frame Completion Results Flags

229

3.10

Frame Preview Format 

229

3.11

Video IO Support

229

Contents

11

3.12

Video Connection Modes

230

3.13

Link Configuration

230

3.14

Audio Sample Rates

230

3.15

Audio Sample Types

230

3.16

DeckLink Information ID 

231

3.17

DeckLink Attribute ID

231

3.18

DeckLink Configuration ID

234

3.19

Audio Output Stream Type

240

3.20

Analog Video Flags

240

3.21

Audio Connection Modes

240

3.22

Audio Output Selection switch 

240

3.23

Output Conversion Modes

241

3.24

Input Conversion Modes

241

3.25

Video Input Format Changed Events

242

3.26

Detected Video Input Format Flags

242

3.27

Capture Pass Through Mode 

242

3.28

Display Mode Characteristics 

243

3.29

Video 3D packing format 

243

3.30

Timecode Format

243

3.31

Timecode Flags

244

3.32

Timecode BCD

244

3.33

Deck Control Mode 

245

3.34

Deck Control Event 

245

3.35

Deck Control VTR Control States 

245

3.36

Deck Control Status Flags 

246

3.37

Deck Control Export Mode Ops Flags 

246

3.38

Deck Control error 

247

3.39

Genlock Reference Status 

247

3.40

Idle Video Output Operation 

248

3.41

Device Busy State 

248

3.42

DeckLink Device Notification 

248

3.43

Streaming Device Mode 

248

3.44

Streaming Device Encoding Frame Rates 

249

3.45

Streaming Device Encoding Support 

249

3.46

Streaming Device Codecs 

249

3.47

Streaming Device H264 Profile

250

3.48

Streaming Device H264 Level 

250

3.49

Streaming Device H264 Entropy Coding 

250

3.50

Streaming Device Audio Codec 

251

3.51

Streaming Device Encoding Mode Properties 

251

3.52

Audio Formats

251

3.53

Deck Control Connection

251

3.54

Video Encoder Frame Coding Mode

252

3.55

DeckLink Encoder Configuration ID

252

3.56

Device Interface252

Contents

12

3.57

Packet Type

253

3.58

DeckLink Status ID

253

3.59

Video Status Flags

255

3.60

Duplex Mode

255

3.61

Frame Metadata ID

255

3.62

DNxHR Levels

256

3.63

Panel Type

256

3.64

Ancillary Packet Format

256

3.65

Colorspace

256

3.66

HDMI Input EDID ID

257

3.67

Dynamic Range

257

3.68

Supported Video Mode Flags

257

3.69

Profile Identifier

258

3.70

HDMI Timecode Packing

258

3.71

Internal Keying Ancillary Data Source

258

3.72

Ethernet Link State

258

3.73

Mezzanine Type

259

3.74

Video Format Flags

259

Contents

13

Introduction
WelcomeThanks for downloading the Blackmagic Design DeckLink Software Developers Kit.

Overview
The DeckLink SDK provides a stable, cross-platform interface to Blackmagic Design capture andplayback products.
The SDK provides both low-level control of hardware and high-level interfaces to allow developers toeasily 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, macOS andLinux platforms.
The libraries supporting the Blackmagic SDK are shipped as part of the product installers for eachsupported product line. Applications built against the interfaces shipped in the SDK will dynamicallylink against the library installed on the end-user’s system.
The SDK interface is modeled on Microsoft’s Component Object Model (COM). On Microsoft
Windows platforms, it is provided as a native COM interface registered with the operating system.
On other platforms application code is provided to allow the same COM style interface to be used.
The COM model provides a paradigm for creating flexible and extensible interfaces withminimal overhead.
You can download the DeckLink SDK from the Blackmagic Design support center at:
www.blackmagicdesign.com/support
The product family is Capture and Playback.
The Blackmagic Design Developer website provides video tutorials and FAQs for developing software
for Desktop Video products.
Please visit at www.blackmagicdesign.com/developer
If you’re looking for detailed answers regarding technologies used by Blackmagic Design, such as codecs,
core media, APIs, SDK and more, visit the Blackmagic Software Developers Forum. The forum is a helpfulplace for you to engage with both Blackmagic support staff and other forum members who can answer
developer specific questions and provide further information. The Software Developers Forum can befound within the Blackmagic Design Forum at forum.blackmagicdesign.com
If you wish to ask questions outside of the software developers forum, please contact us at:
developer@blackmagicdesign.com

Introduction

14

Section 1 — API Design
1.1

API Design

1.1.1

Supported Products
The DeckLink SDK provides programmatic access to a wide variety of Blackmagic Design products. The
term “DeckLink” is used as a generic term to refer to the supported products.
Playback and Capture support is provided for devices in the DeckLink, Intensity, UltraStudio and Teranex
product lines. Capture support is provided for the Cintel Scanner, Cinema Camera and Hyperdeck
Studio products.

1.1.2

Supported Operating Systems
The DeckLink SDK is supported on macOS, Windows and Linux operating systems. The release notes
supplied with the DeckLink packages include details of supported operating system versions.

1.1.3

3rd Party Product and Feature Support

1.1.3.1

NVIDIA GPUDirect support
NVIDIA GPUDirect is supported on Windows and Linux for x86_64 architecture where those platforms arealso supported by NVIDIA. GPUDirect support requires the use of the DVP library supplied by NVIDIA.
See the LoopThroughWithOpenGLCompositing for a detailed example of integrating the DeckLink API
and NVIDIA GPUDirect.

1.1.3.2

AMD DirectGMA support
AMD DirectGMA is supported on Windows and Linux for x86_64 architecture where those platforms arealso supported by AMD. DirectGMA support requires the use of the GL_AMD_pinned_memory GL
extension supported by compatible AMD OpenGL drivers.
See the LoopThroughWithOpenGLCompositing for a detailed example of integrating the DeckLink API
and AMD DirectGMA.

1.1.4

Object Interfaces
The API provides high-level interfaces to allow capture & playback of audio and video with frame bufferingand scheduling as well as low-level interfaces for controlling features available on different capture
card models.
Functionality within the API is accessed via “object interfaces”. Each object in the system may inherit fromand be accessed via a number of object interfaces. Typically the developer is able to interact with object
interfaces and leave the underlying objects to manage themselves.
Each object interface class has a Globally Unique ID (GUID) called an “Interface ID”. On platforms withnative 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.

Section 1 — API Design15

1.1.5

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

1.1.6

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

1.1.6.1

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

1.1.6.2

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

1.1.6.3

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

1.1.6.4

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

Section 1 — API Design

16

1.2

Interface Reference
Every object interface subclasses the IUnknown interface.

1.2.1

IUnknown Interface
Each API interface is a subclass of the standard COM base class – IUnknown. The IUnknown object
interface provides reference counting and the ability to look up related interfaces by interface ID. Theinterface ID mechanism allows interfaces to be added to the API without impacting existing applications.
Public Member Functions

1.2.1.1

MethodDescription

QueryInterface

Provides access to supported child interfaces of the object.

AddRefIncrements the reference count of the object.

ReleaseDecrements the reference count of the object. When the finalreference is removed, the object is freed.

IUnknown::QueryInterface method
The QueryInterface method looks up a related interface of an object interface.
SyntaxHRESULT

QueryInterface(REFIID id, void **outputInterface);

Parameters
Name

Direction

Description

idinInterface ID of interface to lookup

outputInterfaceout

New object interface or NULL on failure

Return Values
Value

Description

E_NOINTERFACE

Interface was not found.

S_OK

Success.

Section 1 — API Design17

1.2.1.2

IUnknown::AddRef method
The AddRef method increments the reference count for an object interface.
SyntaxULONG

AddRef();Return Values

1.2.1.3

Value

DescriptionCount

New reference count – for debug purposes only.

IUnknown::Release method
The Release method decrements the reference count for an object interface. When the last reference isremoved from an object, the object will be destroyed.
Syntax
ULONG

Release();Return Values
Value

DescriptionCount

New reference count – for debug purposes only.

Section 1 — API Design18Section 2 — DeckLink API
2.1

Using the DeckLink API in a project
The supplied sample applications provide examples of how to include the DeckLink API ina project on each supported platform.
To use the DeckLink API in your project, one or more files need to be included:
Windows

DeckLink X.Y\Win\Include\DeckLinkAPI.idl

macOS

DeckLink X.Y/Mac/Include/DeckLinkAPI.h
DeckLink X.Y/Mac/Include/DeckLinkAPIDispatch.cpp

Linux

DeckLink X.Y/Linux/Include/DeckLinkAPI.h
DeckLink X.Y/Linux/Include/DeckLinkAPIDispatch.cpp

You can also include the optional header file “DeckLinkAPIVersion.h”. It defines two
macros containing the SDK version numbers which can be used at runtime by yourapplication to compare the version of the DeckLink API it is linked to with the version of the
SDK used at compile time.

2.2

Sandboxing support on macOSThe DeckLink API can be accessed from sandboxed applications if the following
requirements are met:
— Application is built against macOS 10.7 or later— Ensure App Sandbox capability is added in your application target’s Signings andCapabilities settings,— Insert the following properties into your application’s entitlements file:
Key

Type

Value

com.apple.security.temporary-exception.machlookup.global-nameStringcom.blackmagic-design.desktopvideo.
DeckLinkHardwareXPCService

com.apple.security.temporary-exception.sharedpreference.read-onlyStringcom.blackmagic-design.desktopvideo.
prefspanel

Refer to the entitlements file in the SignalGenerator sample application in the SDK.
Further information can be found in the App Sandbox Design Guide available on Apple’s
Developer site.

2.3

Accessing DeckLink devices
Most DeckLink API object interfaces are accessed via the IDeckLinkIterator object. How areference to an IDeckLinkIterator is obtained varies between platforms depending on theirlevel of support for COM.

Section 2 — DeckLink API

19

2.3.1

Windows
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.3.2

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

2.4

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.4.1

CaptureAn application performing a standard streaming capture operation should perform the following steps:— If desired, enumerate the supported capture video modes by calling
IDeckLinkInput::GetDisplayModeIterator. For each reported capture mode, call
IDeckLinkInput::DoesSupportVideoMode to check if the combination of the video mode and pixel
format is supported.
— IDeckLinkInput::EnableVideoInput— IDeckLinkInput::EnableAudioInput— IDeckLinkInput::SetCallback— IDeckLinkInput::StartStreams
While streams are running:
Receive calls to IDeckLinkInputCallback::VideoInputFrameArrived
with video frame and corresponding audio packet— IDeckLinkInput::StopStreams
If audio is not required, the call to IDeckLinkInput::EnableAudioInput may be omitted and the
IDeckLinkInputCallback::VideoInputFrameArrived callback will receive NULL audio packets.

Section 2 — DeckLink API

20

2.4.2

Playback
An application performing a standard streaming playback operation should perform the following steps:— IDeckLinkOutput::DoesSupportVideoMode to check if the combination of the video mode and pixel
format is supported.
— IDeckLinkOutput::EnableVideoOutput— IDeckLinkOutput::EnableAudioOutput— IDeckLinkOutput::SetScheduledFrameCompletionCallback— IDeckLinkOutput::SetAudioCallback— 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
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 IDeckLinkOutput::EnableAudioOutput,
IDeckLinkOutput::SetAudioCallback and IDeckLinkOutput::BeginAudioPreroll may be omitted.
If pre-roll is not required initial IDeckLinkOutput::ScheduleVideoFrame calls and the callto IDeckLinkOutput::BeginAudioPreroll and IDeckLinkOutput::EndAudioPreroll may be omitted.

2.4.3

3D Functionality
3D (dual-stream) capture and playback is supported by certain DeckLink devices such as the DeckLink 4K
Extreme. The 3D functionality is only available over HDMI or SDI, where Channel A and Channel B
represent the left and right eyes. The 3D packing must be manually set when connecting topre‑HDMI 1.4 devices. When capturing from an HDMI 1.4 compliant source, the 3D packing format willautomatically detected, and cannot be overridden. When outputting to an HDMI 1.4 compliant device /monitor, the packing format will be adjusted according to the device / monitor’s capabilities, but can be
manually changed. Refer to the IDeckLinkConfiguration Interface and
BMDVideo3DPackingFormat sections for more information on getting and setting the packing format.

NOTE Automatic mode detection is not available for UHD and DCI 4K 3D dual-link SDI modes.

2.4.3.1

3D Capture
An application performing a streaming 3D capture operation should perform the following steps:— If desired, enumerate the supported capture video modes by calling
IDeckLinkInput::GetDisplayModeIterator. For each reported capture mode, check for the presenceof the bmdDisplayModeSupports3D flag in the return value of IDeckLinkDisplayMode::GetFlag
indicating that this mode is supported for 3D capture. Call IDeckLinkInput::DoesSupportVideoModewith the bmdVideoInputDualStream3D flag to check if the combination of the video mode and pixel
format is supported.
— Call IDeckLinkInput::EnableVideoInput with the bmdVideoInputDualStream3D flag.
— IDeckLinkInput::EnableAudioInput— IDeckLinkInput::SetCallback— IDeckLinkInput::StartStreams

Section 2 — DeckLink API

21

While streams are running:
Receive calls to IDeckLinkInputCallback::VideoInputFrameArrived with left eye video frameand corresponding audio packet.
Inside the callback:Call IDeckLinkVideoInputFrame::QueryInterface with IID_IDeckLinkVideoFrame3DExtensions
IDeckLinkVideoFrame3DExtensions::GetFrameForRightEye The returned frame object must be
released by the caller when no longer required.
— IDeckLinkInput::StopStreams

2.4.3.2

3D Playback
To support 3D playback, your application must provide the API with a video frame object which
implements the IDeckLinkVideoFrame interface and returns a valid object implementing the
IDeckLinkVideoFrame3DExtensions interface when its QueryInterface method is called with
IID_IDecklinkVideoFrame3DExtensions. This can be achieved by providing your own class which:— Subclasses both IDeckLinkVideoFrame and IDeckLinkVideoFrame3DExtensions interfaces— Returns a pointer to itself (cast to IDeckLinkVideoFrame3DExtensions) when its
QueryInterface method is called with IID_IDeckLinkVideoFrame3DExtensions.
— Implements all the methods in the IDeckLinkVideoFrame andIDeckLinkVideoFrame3DExtensions classes.
An application performing a streaming 3D playback operation should perform the following steps:
Check if 3D is supported for the desired video mode with
IDeckLinkOutput::DoesSupportVideoMode called with bmdVideoOutputDualStream3D.
— Call IDeckLinkOutput::EnableVideoOutput with the bmdVideoOutputDualStream3D flag set.
— IDeckLinkOutput::EnableAudioOutput— IDeckLinkOutput::SetScheduledFrameCompletionCallback— IDeckLinkOutput::SetAudioCallback— IDeckLinkOutput::BeginAudioPreroll
While more frames or audio need to be pre-rolled:
Create a video frame object that subclasses IDeckLinkVideoFrameand IDeckLinkVideoFrame3DExtensions as explained above.
— IDeckLinkOutput::ScheduleVideoFrame
Return audio data from IDeckLinkAudioOutputCallback::RenderAudioSamples
When audio preroll is complete, call IDeckLinkOutput::EndAudioPreroll— IDeckLinkOutput::StartScheduledPlayback
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 IDeckLinkOutput::EnableAudioOutput,
IDeckLinkOutput::SetAudioCallback and IDeckLinkOutput::BeginAudioPreroll may be omitted.
If pre-roll is not required initial IDeckLinkOutput::ScheduleVideoFrame calls and the call to
IDeckLinkOutput::BeginAudioPreroll and IDeckLinkOutput::EndAudioPreroll may be omitted.

Section 2 — DeckLink API

22

2.4.4DeckLink Device Notification
A callback notification can be provided to an application when a Thunderbolt or USB 3.0 based DeckLink
device is connected or disconnected.
An application that supports connection notification should perform the following steps:— Create a callback class that subclasses IDeckLinkDeviceNotificationCallback and implements all of
its methods. The callback class will be called asynchronously from an API private thread. Create an
instance of the callback class.
— Call IDeckLinkDiscovery::InstallDeviceNotifications and provide the
IDeckLinkDeviceNotificationCallback object.
— IDeckLinkDeviceNotificationCallback::DeckLinkDeviceArrived is called for all currentlyconnected devices.
— When a DeckLink device is connected after the initial reporting of devices then
IDeckLinkDeviceNotificationCallback::DeckLinkDeviceArrived will be called.
— When a DeckLink device is removed,
IDeckLinkDeviceNotificationCallback::DeckLinkDeviceRemoved is called on an
API-private thread.
— Before the application exits, call IDeckLinkDiscovery::UninstallDeviceNotifications.

2.4.5

Streaming Encoder
Streaming encoder functionality is supported by certain DeckLink devices such as the H.264 Pro
Recorder. Uncompressed video and audio streams may be encoded into a compressed bitstream andmade available to suitable applications involving compressed video and audio.

2.4.5.1

Streaming Encoder Capture
An application performing a typical streaming encoder capture operation should perform thefollowing steps:— E numerate the preset video encoding modes by calling
IBMDStreamingDeviceInput::GetVideoEncodingModePresetIterator.
For each reported video encoding mode call
IBMDStreamingDeviceInput::GetCurrentDetectedVideoInputMode and
IBMDStreamingDeviceInput::DoesSupportVideoEncodingMode to check if the current video input
mode and video encoding mode are supported.
— If desired, call IBMDStreamingVideoEncodingMode::CreateMutableVideoEncodingMode to change
the encoder bitrate or other encoder settings.
— IBMDStreamingDeviceInput::SetVideoEncodingMode— IBMDStreamingDeviceInput::SetCallback— IBMDStreamingDeviceInput::StartCapture
While capture is running:receive calls to IBMDStreamingH264InputCallback::MPEG2TSPacketArrived
with MPEG transport stream data to process both compressed video and audio alternatively, receive
calls to IBMDStreamingH264InputCallback::H264NALPacketArrived and
IBMDStreamingH264InputCallback::H264AudioPacketArrived to process compressed video andaudio data separately— IBMDStreamingDeviceInput::StopCapture

Section 2 — DeckLink API

23

2.4.6

Automatic Mode Detection
The automatic mode detection feature will notify an application when a property of the video input signal
changes. This feature is supported on certain DeckLink devices. For an example of using automatic mode
detection, please refer the AutomaticModeDetection sample in the DeckLink SDK.
To use this feature please refer to the following steps:— Call IDeckLinkProfileAttributes::GetFlag with the BMDDeckLinkSupportsInputFormatDetection flag
to check that the DeckLink hardware supports the automatic format detection feature.
— Create a callback class that subclasses from IDeckLinkInputCallback and implements all of its
methods. The IDeckLinkInputCallback::VideoInputFormatChanged method will be called when achange in the property of the video signal has been detected.
— Install a callback by calling IDeckLinkInput::SetCallback and referencing an instance of yourcallback class.
— Call IDeckLinkInput::EnableVideoInput with an initial video mode and pixel format and set thebmdVideoInputEnableFormatDetection flag.
— Call IDeckLinkInput::EnableAudioInput.
— Call IDeckLinkInput::StartStreams to begin capture.
While the input streams are running:
If a change in a property of the input video signal is detected then
IDeckLinkInputCallback::VideoInputFormatChanged will be called in your callback object with the
new video properties provided in the parameters.
If the video mode or pixel format has changed, then the following sequence could be used to restart
capture with the new settings:
IDeckLinkInput::PauseStreams Call IDeckLinkInput::EnableVideoInput with the detected video
mode and pixel format.IDeckLinkInput::FlushStreams IDeckLinkInput::StartStreams— Call IDeckLinkInput::StopStreams to stop capture.
— Call IDeckLinkInput::DisableVideoInput— Call IDeckLinkInput::DisableAudioInput

2.4.7

Ancillary Data functionality
The capture or output of vertical ancillary data (VANC) is supported by certain DeckLink device models.
Ancillary Data support is only available for SDI, Optical SDI, Ethernet and Optical Ethernet connections.
The lines of VANC that are accessible are dependent upon the model of the DeckLink device. Currently
horizontal ancillary data (HANC) access is not supported.

2.4.7.1

VANC Capture
An application performing VANC data capture should perform the following steps:— IDeckLinkInput::EnableVideoInput
Call IDeckLinkProfileAttributes::GetFlag with the
BMDDeckLinkVANCRequires10BitYUVVideoFrames flag to check whether the DeckLink hardware
supports VANC only when the active picture and ancillary data are both 10-bit YUV pixel format.
— IDeckLinkInput::EnableAudioInput— IDeckLinkInput::SetCallback— IDeckLinkInput::StartStreams
While streams are running:
Receive calls to IDeckLinkInputCallback::VideoInputFrameArrived
Inside the callback:Call IDeckLinkVideoFrame::QueryInterface with IID_IDeckLinkVideoFrameAncillaryPackets.

Section 2 — DeckLink API

24

As the IDeckLinkVideoFrameAncillaryPackets object has a reference to the IDeckLinkVideoFrame
input frame, ensure that it is released in a timely manner, otherwise the capture will run out ofavailable frames.
If the DID/SDID for the ancillary packet is known, then call
IDeckLinkVideoFrameAncillaryPackets::GetFirstPacketByID.
Check that S_OK is returned to confirm an ancillary packet with matching DID/SDID is found.
Otherwise, enumerate the ancillary packets in the video frame by calling
IDeckLinkVideoFrameAncillaryPackets::GetPacketIterator.
— IDeckLinkAncillaryPacket::GetBytes
The output packet payload will be converted to the requested BMDAncillaryPacketFormat

2.4.7.2

VANC Output— Call IDeckLinkOutput::EnableVideoOutput with the bmdVideoOutputVANC flag set.
Call IDeckLinkProfileAttributes::GetFlag with the
BMDDeckLinkVANCRequires10BitYUVVideoFrames flag to check whether the DeckLink hardware
supports VANC only when the active picture and ancillary data are both 10-bit YUV pixel format.
— Create a ancillary packet object that subclasses IDeckLinkAncillaryPacket, implementing all methodsof the IDeckLinkAncillaryPacket class.
— IDeckLinkAncillaryPacket::GetBytes
Implement to provide pointer to packet data in playback operation.
The packet payload data shall be implemented with at least one BMDAncillaryPacketFormat.
The driver will automatically convert to the correct format on output.
— IDeckLinkOutput::CreateVideoFrame
Call IDeckLinkVideoFrame::QueryInterface with IID_IDeckLinkVideoFrameAncillaryPackets.
As the IDeckLinkVideoFrameAncillaryPackets object has a reference to the IDeckLinkVideoFrame
input frame, ensure that it is released in a timely manner, otherwise the playback will run out ofavailable frames.
— IDeckLinkVideoFrameAncillaryPackets::AttachPacket
Attach ancillary packet to video frame for playback.
— IDeckLinkOutput::ScheduleVideoFrame— IDeckLinkOutput::StartScheduledPlayback

NOTE For applications outputting custom video frame objects that implement the
IDeckLinkVideoFrame interface (for example for 3D playback or HDR metadata output),the class must provide a valid object when its QueryInterface is called with
IID_IDeckLinkVideoFrameAncillaryPackets. The return object interface from QueryInterface should
be obtained with CoCreateInstance with CLSID_CDeckLinkVideoFrameAncillaryPackets (Windows)
or CreateVideoFrameAncillaryPacketsInstance (macOS and Linux).

Section 2 — DeckLink API25

2.4.8KeyingAlpha keying allows an application to either superimpose a key frame over an incoming video feed
(internal keying) or to send fill and key to an external keyer (external keying).
The alpha keying functionality is supported on certain DeckLink models.
For an example of using the keying functionality please refer to GdiKeyer sample application in the
DeckLink SDK.
An application performing keying should use the following steps:— Call IDeckLinkProfileAttributes::GetFlag using BMDDeckLinkSupportsInternalKeying or
BMDDeckLinkSupportsExternalKeying to check that the DeckLink hardware supports internal/
external keying— Create video frames with pixel formats that have alpha channels (such as bmdFormat8BitARGB or
bmdFormat8BitBGRA).
— IDeckLinkOutput::EnableVideoOutput
Call IDeckLinkKeyer::Enable with FALSE for internal keying or TRUE for external keying
Set a fixed level of blending using IDeckLinkKeyer::SetLevel
Alternatively set ramp up or down blending using IDeckLinkKeyer::RampUp
or IDeckLinkKeyer::RampDown
The level of blending of each pixel will depend on the value in the alpha channel and the keying
level setting.
— IDeckLinkOutput::SetScheduledFrameCompletionCallback— Pre-roll video frames using IDeckLinkOutput::ScheduleVideoFrame— IDeckLinkOutput::StartScheduledPlayback
While playback is running schedule video frames fromDeckLinkVideoOutputCallback::ScheduledFrameCompleted
When playback has finished:
IDeckLinkKeyer::Disable IDeckLinkOutput::DisableVideoOutput

2.4.9

Timecode/Timecode user bits
The capture and output of VITC and RP188 timecodes are supported on certain DeckLink models. VITC
timecodes are only supported with SD video modes. On non-4K DeckLink devices, RP188 timecodes are
only supported with HD video modes.
To use this feature please refer to the following points:

2.4.9.1

Timecode Capture
An application performing timecode capture should perform the following steps. For an example oftimecode capture please refer to the CapturePreview sample application in the DeckLink SDK.
— For HDMI capture, call IDeckLinkProfileAttributes::GetFlag using
BMDDeckLinkSupportsHDMITimecode to check that the DeckLink hardware supports
HDMI timecode— IDeckLinkInput::EnableVideoInput— IDeckLinkInput::EnableAudioInput— IDeckLinkInput::SetCallback— IDeckLinkInput::StartStreams
While streams are running:
Receive calls to IDeckLinkInputCallback::VideoInputFrameArrived
with video frame and corresponding audio packet
Call IDeckLinkVideoInputFrame::GetTimecode

Section 2 — DeckLink API

26

— IDeckLinkTimecode::GetFlags— IDeckLinkTimecode::GetTimecodeUserBits(User bits are not supported for HDMI timecode)— IDeckLinkInput::StopStreams— IDeckLinkInput::DisableVideoInput

2.4.9.2

Timecode Output
An application performing timecode output should perform the following steps. For an example oftimecode output please refer to the Linux SignalGenerator sample application in the DeckLink SDK.
— For HDMI output, call IDeckLinkProfileAttributes::GetFlag using
BMDDeckLinkSupportsHDMITimecode to check that the DeckLink hardware supports
HDMI timecode— Call IDeckLinkOutput::EnableVideoOutput with either bmdVideoOutputVITC
or bmdVideoOutputRP188— IDeckLinkOutput::EnableAudioOutput— IDeckLinkOutput::SetScheduledFrameCompletionCallback— IDeckLinkOutput::SetAudioCallback— IDeckLinkOutput::BeginAudioPreroll
While more frames or audio need to be pre-rolled:
Create video frames with IDeckLinkOutput::CreateVideoFrame
Set the timecode into the frame with IDeckLinkMutableVideoFrame::SetTimecodeor IDeckLinkMutableVideoFrame::SetTimecodeFromComponents— IDeckLinkOutput::ScheduleVideoFrame
Return audio data from IDeckLinkAudioOutputCallback::RenderAudioSamples
When audio preroll is complete, call IDeckLinkOutput::EndAudioPreroll— IDeckLinkOutput::StartScheduledPlayback
While playback is running:
Create video frames and set the timecode.
Schedule more video frames from IDeckLinkVideoOutputCallback::ScheduledFrameCompleted
Schedule more audio from IDeckLinkAudioOutputCallback::RenderAudioSamples— IDeckLinkOutput::StopScheduledPlayback— IDeckLinkOutput::DisableVideoOutput

2.4.10H.265 Capture
Certain DeckLink devices support encoded (e.g. H.265) capture in addition to regular
uncompressed capture.

NOTE the Encoded Capture interface is distinct from the H.264 only ‘Streaming Encoder’ interface.

Section 2 — DeckLink API27

2.4.10.1

Encoded Capture
An application performing an encoded capture operation should perform the following steps:— Obtain a reference to the IDeckLinkEncoderInput interface from IDeckLinkInput
via QueryInterface— If desired, enumerate the supported encoded capture video modes bycalling IDeckLinkEncoderInput::GetDisplayModeIterator.
— For each reported capture mode, call IDeckLinkEncoderInput::DoesSupportVideoMode to check if
the combination of the video mode and pixel format is supported.
— IDeckLinkEncoderInput::EnableVideoInput— IDeckLinkEncoderInput::EnableAudioInput— IDeckLinkEncoderInput::SetCallback— IDeckLinkEncoderInput::StartStreams
While streams are running:receive calls to IDeckLinkEncoderInputCallback::VideoPacketArrived
with encoded video packets
receive calls to IDeckLinkEncoderInputCallback::AudioPacketArrived
with audio packets— IDeckLinkInput::StopStreams
If audio is not required, the call to IDeckLinkEncoderInput::EnableAudioInput may be omitted and the
IDeckLinkEncoderInputCallback::AudioPacketArrived callback will not be called.

2.4.11

Device Profiles
Certain DeckLink devices such as the DeckLink 8K Pro, the DeckLink Quad 2 and the DeckLink Duo 2
support multiple profiles to configure the capture and playback behavior of its sub-devices.
For the DeckLink Duo 2 and DeckLink Quad 2, a profile is shared between any 2 sub‑devices that utilize
the same connectors. For the DeckLink 8K Pro, a profile is shared between all 4 sub-devices. Any
sub-devices that share a profile are considered to be part of the same profile group. To enumerate thesub-devices in a group, the IDeckLinkProfile::GetPeers method should be used.
A change in profile is applied to all sub-devices in the group. The following is a list of items that are
affected by a profile change:— Profile ID attribute BMDDeckLinkProfileID.
— SDI link configuration attributes BMDDeckLinkSupportsDualLinkSDI and
BMDDeckLinkSupportsQuadLinkSDI.
— Supported Display Modes. An application should recheck the outputs of
IDeckLinkInput::DoesSupportVideoMode and IDeckLinkOutput::DoesSupportVideoMode.
— Keying support attributes BMDDeckLinkSupportsInternalKeying and
BMDDeckLinkSupportsExternalKeying.
— Sub-devices may change duplex mode or become inactive. An application can check the duplex
mode with attribute BMDDeckLinkDuplex.
— Other attributes accessible by the IDeckLinkProfileAttributes object interface.
The tables and illustrations below demonstrate the grouping of sub-devices and how the relationship tophysical connectors varies with different profiles.

Section 2 — DeckLink API

28

DeckLink 8K Pro
SDI 4
SDI 3
SDI 2
SDI 1
Reference In

4 sub-devices
profile2 sub-devices
profile1 sub-device
full-duplex profile

1 sub-device
half-duplex profile(bmdProfileFourSub
DevicesHalfDuplex)(bmdProfileTwoSub
DevicesFullDuplex)(bmdProfileOneSub
DevicesFullDuplex)(bmdProfile OneSub
DevicesHalfDuplex)0

SDI 1 (in/out)

SDI 1 (in/key)
SDI 2 (out/fill)

SDI 1 (CH-B in)
SDI 2 (CH-A in)
SDI 3 (CH-B out/key)
SDI 4 (CH-A out/fill)

SDI 1 (CH-D in/out)
SDI 2 (CH-C in/out)
SDI 3 (CH-B in/out/key)
SDI 4 (CH-A in/out//fill)1

SDI 3 (in/out)

SDI 3 (in/key)
SDI 4 (out/fill)

­—

—

2

SDI 2 (in/out)

—

—

—

3

SDI 4 (in/out)

—

—

—

Sub-device
index

DeckLink Quad 2
SDI 8
SDI 7
SDI 6
SDI 5
SDI 4
SDI 3
SDI 2
SDI 1
Reference In

Sub-deviceindex

2 sub-devices profile

1 sub-device profile(bmdProfileTwoSubDevicesHalfDuplex)(bmdProfileOneSubDeviceFullDuplex)

0

SDI 1

SDI 1 (in/key) & SDI 2 (out/fill)

1

SDI 3

SDI 3 (in/key) & SDI 4 (out/fill)

2

SDI 5

SDI 5 (in/key) & SDI 6 (out/fill)

3

SDI 7

SDI 7 (in/key) & SDI 8 (out/fill)

4

SDI 2

—

5

SDI 4

—

6

SDI 6

—

7

SDI 8

—

Section 2 — DeckLink API

29

DeckLink Duo 2
SDI 4
SDI 3
SDI 2
SDI 1
Reference In

2.4.11.1

Sub-deviceindex

2 sub-device profile

1 sub-device profile(bmdProfileTwoSubDevicesHalfDuplex)(bmdProfileOneSubDeviceFullDuplex)

0

SDI 1

SDI 1 (in/key) & SDI 2 (out/fill)

1

SDI 3

SDI 3 (in/key) & SDI 4 (out/fill)

2

SDI 2

—

3

SDI 4

—

Determine the current profile ID
An application can determine the current profile for an IDeckLink device by performing thefollowing steps:— Call IDeckLink::QueryInterface with IID_DeckLinkProfileAttributes.
— Call IDeckLinkProfileAttributes::GetInt with identifier BMDDeckLinkProfileID to obtain the ID of thecurrent profile.

2.4.11.2

List the available profiles
An application can list the available profiles for an IDeckLink device by performing the following steps:— Obtain an IDeckLinkProfileManager interface object by calling IDeckLink::QueryInterface
with IID_IDeckLinkProfileManager.
If result is E_NOINTERFACE, then the DeckLink device has only one profile (the current profile).
— Obtain a IDeckLinkProfileIterator by calling IDeckLinkProfileManager::GetProfiles and enumerate
the supported profiles for the device by calling IDeckLinkProfileIterator::Next.
— For each returned IDeckLinkProfile interface object:
Call IDeckLinkProfile::QueryInterface with IID_DeckLinkProfileAttributes.
Call IDeckLinkProfileAttributes::GetInt with identifier BMDDeckLInkProfileID to obtain the profile ID.

2.4.11.3

Select a new profile
An application can select a new profile for an IDeckLink device by performing the following steps:— Obtain an IDeckLinkProfileManager interface object by calling IDeckLink::QueryInterface
with IID_IDeckLinkProfileManager.
— Obtain an IDeckLinkProfile interface object by calling IDeckLinkProfileManager::GetProfile with therequired BMDDeckLinkProfileID.
— Activate the required profile with IDeckLinkProfile::SetActive.

Section 2 — DeckLink API30

2.4.11.4

Handle a profile change notification
A callback can be provided to an application when a profile is changed. If the application does not
implement a profile callback, the running streams may be halted unprompted by the driver if the
profile changes.
An application that supports profile changing notification should perform the following steps:— Create a callback class that subclasses from IDeckLinkProfileCallback and implement all of its
methods. The callback calls will be called asynchronously from an API private thread.
— Obtain an IDeckLinkProfileManager interface object by calling IDeckLink::QueryInterface with
IID_IDeckLinkProfileManager.
— Install the callback by calling IDeckLinkProfileManager::SetCallback and referencing yourIDeckLinkProfileCallback object.
During profile change:
Receive call to IDeckLinkProfileCallback::ProfileChanging, stop any active streams if required asdetermined by the streamsWillBeForcedToStop argument.
Receive call to IDeckLinkProfileCallback::ProfileActivated, when the new profile is active. The
application should rescan any attributes and display modes for the new profile.
NOTE Profile change callbacks will occur if another application has changed the active
profile of the device.

2.4.12HDR Metadata
HDR Metadata capture and playback is supported by certain DeckLink devices such as
the DeckLink 4K Extreme 12G. An application performing capture or playback with HDR Metadata should
first verify support of this feature by calling IDeckLinkAttribute::GetFlag with attribute
BMDDeckLinkSupportsHDRMetadata. The IDeckLinkVideoFrameMetadataExtensions object interface
provides methods to query metadata associated with a video frame.

2.4.12.1

CEA/SMPTE Static HDR Capture
When capturing CEA Static HDR Metadata from an HDMI source, an application should first write to the
HDMI EDID with the supported dynamic range standards. This can be achieved with the following steps:— Obtain a reference to the IDeckLinkHDMIInputEDID interface from IDeckLink via
IUnknown::QueryInterface.
— Configure the supported dynamic range standards by calling IDeckLinkHDMIInputEDID::SetInt withconfiguration item bmdDeckLinkHDMIInputEDIDDynamicRange with one or more values defined by
BMDDynamicRange.
— Write the supported dynamic range EDID value to DeckLink hardware by calling
IDeckLinkHDMIInputEDID::WriteToEDID.
An application performing capture of video frames with HDR Metadata should perform the following steps:— IDeckLinkInput::EnableVideoInput— IDeckLinkInput::SetCallback— IDeckLinkInput::StartStreams
While streams are running:
Receive calls to IDeckLinkInputCallback::VideoInputFrameArrived
Inside the callback:Check that video frame has HDR Metadata by ensuring IDeckLinkVideoFrame::GetFlags has
bmdFrameContainsHDRMetadata flag.

Section 2 — DeckLink API

31

Call IDeckLinkVideoInputFrame::QueryInterface with
IID_IDeckLinkVideoFrameMetadataExtensions.
— IDeckLinkVideoFrameMetadataExtensions::Get* methods can be called to access HDR
Metadata items. See BMDDeckLinkFrameMetadataID enumerator for a full list of supported HDR
Metadata items.
— The IDeckLinkVideoFrameMetadataExtensions object must be released by the caller when nolonger required.

2.4.12.2

CEA/SMPTE Static HDR Playback
In order to output HDR metadata, your application must provide the API with a custom video frame object
which implements the IDeckLinkVideoFrame interface and returns a valid object implementing
the IDeckLinkVideoFrameMetadataExtensions interface when its QueryInterface method is called with
IID_IDeckLinkVideoFrameMetadataExtensions. This can be achieved by providing your own class which:— Subclasses both IDeckLinkVideoFrame and IDeckLinkVideoFrameMetadataExtensions interfaces.
— Returns a pointer to itself (cast to IDeckLinkVideoFrameMetadataExtensions) when its
QueryInterface method is called with IID_IDeckLinkVideoFrameMetadataExtensions.
— Implements all the methods in the IDeckLinkVideoFrame class.
— Specify the HDR metadata items to be queried by implementing methods in the
IDeckLinkVideoFrameMetadataExtensions class. See BMDDeckLinkFrameMetadataID enumerator
for a full list of supported HDR Metadata items.
— Reveal the presence of HDR Metadata in custom frame by returning flag bmdFrameContainsHDRMetadata
when video frame flags are queried with IDeckLinkVideoFrame::GetFlags
An application performing output with HDR Metadata should perform the following steps:— IDeckLinkOutput::EnableVideoOutput— IDeckLinkOutput::SetScheduledFrameCompletionCallback
While more frames or audio need to be pre-rolled:
Create a custom video frame object that subclasses IDeckLinkVideoFrame andIDeckLinkVideoFrameMetadataExtensions as explained above.
— IDeckLinkOutput::ScheduleVideoFrame— IDeckLinkOutput::StartScheduledPlayback
While playback is running:
Schedule more custom video frames from
IDeckLinkVideoOutputCallback::ScheduledFrameCompleted

2.4.12.3

Dolby Vision® Playback
In order to output Dolby Vision, applications must provide the API with a custom video frame object which
implements the IDeckLinkVideoFrame interface and returns a valid object implementing the
IDeckLinkVideoFrameMetadataExtensions interface when its IUnknown::QueryInterface method iscalled with IID_IDeckLinkVideoFrameMetadataExtensions. This can be achieved by creating your own
class which:— Subclasses both IDeckLinkVideoFrame and IDeckLinkVideoFrameMetadataExtensions interfaces.
— Implements all the methods in the IUnknown interface. IUnknown::QueryInterface should provide
casts of itself to IDeckLinkVideoFrame, IDeckLinkVideoFrameMetadataExtensions and IUnknown
as requested.
— Implements all the methods in the IDeckLinkVideoFrame interface. Method
IDeckLinkVideoFrame::GetBytes should output a 12-bit RGB PQ video buffer thatwill be converted to Dolby Vision in the colorspace conversion pipeline.

Section 2 — DeckLink API

32

— Provides Dolby Vision metadata by implementing the IDeckLinkVideoFrameMetadataExtensions::GetBytes
method. When the metadata ID input parameter is bmdDeckLinkFrameMetadataDolbyVision, themethod should output a pointer to the byte buffer consisting of the Dolby Vision metadata. Desktop
Video implements Dolby Vision HDMI Transmission, it does not however depend upon the structureof this data. For details concerning the structure of this data refer to the latest release of Dolby Vision
Metadata For Source and Sink Connections provided by Dolby.
— Provides the frame colorspace by implementing the
IDeckLinkVideoFrameMetadataExtensions::GetInt method and handling metadata ID input
bmdDeckLinkFrameMetadataColorspace.
— Implements all of the other methods for the IDeckLinkVideoFrameMetadataExtensions interface byreturning E_NOTIMPL.
— Reveals the presence of Dolby Vision metadata in the custom frame by returning flag
bmdFrameContainsDolbyVisionMetadata when video frame flags are queried with
IDeckLinkVideoFrame::GetFlags. This flag must continue to be present in all frames until
output is disabled.
An application performing output with HDR Metadata should perform the following steps:— Check that the supported Dolby Vision version of the connected HDMI sink is compatible
with the Dolby Vision metadata by calling IDeckLinkStatus::GetFloat with status item
bmdDeckLinkStatusSinkSupportsDolbyVision.
— Check if Dolby Vision is supported for the desired video mode with
IDeckLinkOutput::DoesSupportVideoMode called with bmdSupportedVideoModeDolbyVision.
— Configure the source colorspace of the output conversion pipeline by calling
IDeckLinkConfiguration::SetInt
with configuration item bmdDeckLinkConfigVideoOutputConversionColorspaceSource with a
BMDColorspace value that matches the colorspace of the output frame.
— Configure the destination colorspace of the output conversion pipelineby calling IDeckLinkConfiguration::SetInt with configuration item
bmdDeckLinkConfigVideoOutputConversionColorspaceDestination with
bmdColorspaceDolbyVisionNative.
— Configure the Dolby Vision Content Mapping version by calling IDeckLinkConfiguration::SetFloat
with configuration item bmdDeckLinkConfigDolbyVisionCMVersion.
— Configure the Dolby Vision mastering monitor luminance by calling IDeckLinkConfiguration::SetFloat
with configuration items bmdDeckLinkConfigDolbyVisionMasterMinimumNits andbmdDeckLinkConfigDolbyVisionMasterMaximumNits.
— Call IDeckLinkOutput::EnableVideoOutput with video output flag bmdVideoOutputDolbyVision.
The output will switch to Dolby Vision once the first frame is displayed.
— If output callbacks are required, call IDeckLinkOutput::SetScheduledFrameCompletionCallbackwith a class that implements IDeckLinkVideoOutputCallback.
While more frames or audio need to be pre-rolled:— Create a custom video frame object that subclasses IDeckLinkVideoFrame andIDeckLinkVideoFrameMetadataExtensions as explained above.
— Output the custom video frame with IDeckLinkOutput::ScheduleVideoFrame.
When sufficient frames have been pre-rolled:— IDeckLinkOutput::StartScheduledPlayback
While playback is running:— Schedule more custom video frames with IDeckLinkOutput::ScheduleVideoFrame. This can be called
within the IDeckLinkVideoOutputCallback::ScheduledFrameCompleted callback context or otherwise.

Dolby, Dolby Vision, and the double-D symbol are registered trademarks of Dolby Laboratories Licensing Corporation.

Section 2 — DeckLink API

33

2.4.13

Synchronized Capture/Playback
Multiple DeckLink devices or sub-devices can be grouped to synchronously start and stop capture or playback.

2.4.13.1

Synchronized Capture
All sources providing the signal to the capture devices must have their clocks synchronized. This can beachieved by providing the sources with a common reference input. However it is not required that thereference input is proved to the DeckLink capture devices. All sources should be configured with thesame frame rate.
— An application performing synchronized capture should perform the following steps:
For each device to synchronize for capture.
— Call IDeckLinkProfileAttributes::GetFlag with the BMDDeckLinkSupportsSynchronizeToCaptureGroupflag to check that the DeckLink hardware supports grouping for synchronized capture.
— Call IDeckLinkConfiguration::SetInt with the bmdDeckLinkConfigCaptureGroup configuration ID,
along with a common integer value for the capture group. This setting is persistent until system reboot.
— Obtain IDeckLinkInput interface and enable each input in the capture group.
— IDeckLinkInput::EnableVideoInput, with the bmdVideoInputSynchronizeToCaptureGroup flag.
— IDeckLinkInput::EnableAudioInput— IDeckLinkInput::SetCallback
For each input in the capture group, call IDeckLinkStatus::GetFlag with the
bmdDeckLinkStatusVideoInputSignalLocked status ID to ensure that the input is locked.
— To start the synchronized capture call IDeckLinkInput::StartStreams on any input device in the group.
— To stop synchronized capture, call IDeckLinkInput::StopStreams on any input device in the group.

2.4.13.2

Synchronized Playback
Each output device in the synchronised playback group requires a common reference. The exception is
the DeckLink 8K Pro, where all sub-devices can synchronize to each other without needing a common
reference input. All output devices should be configured with the same frame rate.
An application performing synchronized playback should perform the following steps— For each device to synchronize for playback,— Call IDeckLinkProfileAttributes::GetFlag with the BMDDeckLinkSupportsSynchronizeToPlaybackGroupflag to check that the DeckLink hardware supports grouping for synchronized playback.
— Call IDeckLinkConfiguration::SetInt with the bmdDeckLinkConfigPlaybackGroup configuration ID, alongwith a common integer value for the playback group. This setting is persistent until system reboot.
— Obtain IDeckLinkOutput interface and enable each output in the playback group.
— IDeckLinkOutput::DoesSupportVideoMode to check if the combination of the video mode and pixel
format is supported.
— IDeckLinkOutput::EnableVideoOutput, with the bmdVideoOutputSynchronizeToPlaybackGroup flag.
— IDeckLinkOutput::EnableAudioOutput— IDeckLinkOutput::SetScheduledFrameCompletionCallback— IDeckLinkOutput::SetAudioCallback— IDeckLinkOutput::BeginAudioPreroll— If a common reference is required, for each output in the playback group, call
IDeckLinkStatus::GetFlag with the bmdDeckLinkStatusReferenceSignalLocked status ID to ensurethat the output is locked to the reference input.
— To start the synchronized playback call IDeckLinkOutput::StartScheduledPlayback on any output inthe group.
— To stop synchronized playback, call IDeckLinkOutput::StopScheduledPlayback on any output in the group.
Section 2 — DeckLink API

34

2.4.14

Video Frame Conversion
The DeckLink API provides SIMD accelerated conversions operations for converting the pixel format of avideo frame. An application performing pixel format conversion should perform the following steps.
— Create the destination frame with the required pixel format— If the DeckLink device has an output interface, the destination video frame can be created with
IDeckLinkOutput::CreateVideoFrame.
— If there is no IDeckLinkOutput interface available, create a class that subclasses
IDeckLinkVideoFrame and implement all methods with the following requirements.
— IDeckLinkVideoFrame::GetWidth and IDeckLinkVideoFrame::GetHeight should return resolution thatis same as source video frame.
— IDeckLinkVideoFrame::GetPixelFormat should return required pixel format (see BMDPixelFormat).
— IDeckLinkVideoFrame::GetRowBytes should return the number of bytes in row for the destination
pixel format.
— IDeckLinkVideoFrame::GetBytes should return a buffer large enough to hold the destination frame.
— Get an instance of the IDeckLinkVideoConversion object interface by calling CoCreateInstance with
CLSID_CDeckLinkVideoConversion (Windows) or CreateVideoConversionInstance (macOSand Linux).
— Call IDeckLinkVideoConversion::ConvertFrame with the source and destination video frames.

2.5

Interface Reference

2.5.1

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

Interface ID

Description

IDeckLink

IID_IDeckLink

IDeckLinkIterator::Next returns IDeckLink interfaces representing
each attached DeckLink device.

Public Member Functions
MethodDescription

Next

Returns an IDeckLink object interface corresponding
to an individual DeckLink device.

Section 2 — DeckLink API

35

2.5.1.1

IDeckLinkIterator::Next method
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.
SyntaxHRESULT

Next (IDeckLink *decklinkInstance);Parameters
Name

Direction

Description

decklinkInstanceout

Next IDeckLink object interface

Return Values

2.5.2

Value

Description

S_FALSENo (more) devices found

E_FAIL

FailureS_OK

Success

IDeckLink Interface
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 therelated IDeckLinkOutput, IDeckLinkInput and IDeckLinkConfiguration interfaces.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkIterator

IID_IDeckLinkIterator

IDeckLinkIterator::Next returns IDeckLink interfaces
representing each attached DeckLink device.

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkOutput object interface may be obtained from
IDeckLink using QueryInterface

IDeckLinkInput

IID_IDeckLinkInput

An IDeckLinkInput object interface may be obtained from
IDeckLink using QueryInterface

IDeckLinkConfiguration

IID_IDeckLinkConfiguration

An IDeckLinkConfiguration object interface may be obtained
from IDeckLink using QueryInterface

IDeckLinkProfileAttributes

IID_
IDeckLinkProfileAttributes

An IDeckLinkProfileAttributes object interface may beobtained from IDeckLink using QueryInterface.

IDeckLinkKeyer

IID_IDeckLinkKeyer

An IDeckLinkKeyer object interface may be obtained from
IDeckLink using QueryInterface.

IDeckLinkDeckControl

IID_IDeckLinkDeckControl

An IDeckLinkDeckControl object may be obtained from
IDeckLink using QueryInterface

IDeckLinkHDMIInputEDID

IID_IDeckLinkHDMIInputEDID

An IDeckLinkHDMIInputEDID object may be obtained
from IDeckLink using QueryInterface

Public Member Functions
MethodDescription

GetModelName

Method to get DeckLink device model name.

GetDisplayName

Method to get a device name suitable for user interfaces

Section 2 — DeckLink API

36

2.5.2.1

IDeckLink::GetModelName method
The GetModelName method can be used to get DeckLink device model name.
SyntaxHRESULT

GetModelName (string *modelName);Parameters
Name

Direction

Description

modelNameout

Hardware model name. This allocated string must be freed by
the caller when no longer required.

Return Values

2.5.2.2

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLink::GetDisplayName method
The GetDisplayName method returns a string suitable for display in a user interface. If the device has acustom label specified (see bmdDeckLinkConfigDeviceInformationLabel), the label will be used as thedisplay name for the device.
Otherwise, the string is made of the model name (as returned by GetModelName) followed by anincreasing number (starting from 1) if more than one instance of a device is present in the system. If not,the returned string is simply the model name.
SyntaxHRESULT

GetDisplayName (string *displayName);Parameters
Name

Direction

Description

displayNameout

The device’s display name. This allocated string must be freed by callerwhen no longer required

Return Values

2.5.3

Value

Description

E_FAIL

Failed to allocate the string

S_OK

Success

IDeckLinkOutput interface
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.
If QueryInterface for an output interface is called on an input only device, then QueryInterface will fail andreturn E_NOINTERFACE.

Section 2 — DeckLink API

37

Related Interfaces
Interface

Interface ID

Description

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkOutput object interface may be obtained from
IDeckLink using QueryInterface

IDeckLinkDisplayMode
Iterator

IID_IDeckLinkDisplayMode
Iterator

IDeckLinkOutput::GetDisplayModeIterator returns an
IDeckLinkDisplayModeIterator object interface

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

IDeckLinkOutput::CreateVideoFrame may be used to create a
new IDeckLinkVideoFrame object interface

IDeckLinkVideoOutput
Callback

IID_IDeckLinkVideoOutput
Callback

An IDeckLinkVideoOutputCallback
object interface may be registeredwith IDeckLinkOutput::SetScheduledFrameCompletionCallback

IDeckLinkAudioOutput
Callback

IID_IDeckLinkAudioOutput
Callback

An IDeckLinkAudioOutputCallback object interface may beregistered with IDeckLinkOutput::SetAudioCallback

IDeckLinkDisplayMode

IID_IDeckLinkDisplayMode

IDeckLinkOutput::GetDisplayMode returns an
IDeckLinkDisplayMode interface object

Public Member Functions
MethodDescription

DoesSupportVideoMode

Check whether a given video mode is supported for output

GetDisplayModeGet a display mode object based on identifier

GetDisplayModeIterator

Get an iterator to enumerate the available output display modes

SetScreenPreviewCallback

Register screen preview callback

EnableVideoOutput

Enable video output

DisableVideoOutput

Disable video output

SetVideoOutputFrameMemoryAllocator

Register custom memory allocator

CreateVideoFrame

Create a video frame

CreateAncillaryData

Create ancillary buffer

DisplayVideoFrameSync

Display a video frame synchronously

ScheduleVideoFrame

Schedule a video frame for display

SetScheduledFrameCompletionCallback

Register completed frame callback

GetBufferedVideoFrameCount

Gets number of frames queued.

EnableAudioOutput

Enable audio output

DisableAudioOutput

Disable audio output

WriteAudioSamplesSync

Play audio synchronously

BeginAudioPreroll

Start pre-rolling audio

EndAudioPreroll

Stop pre-rolling audio

ScheduleAudioSamples

Schedule audio samples for play-back

GetBufferedAudioSampleFrameCount

Returns the number of audio sample frames currently
buffered for output

FlushBufferedAudioSamples

Flush buffered audio

SetAudioCallback

Register audio output callback

Section 2 — DeckLink API

38

Public Member Functions

2.5.3.1

MethodDescription

StartScheduledPlayback

Start scheduled playback

StopScheduledPlayback

Stop scheduled playback

GetScheduledStreamTime

Returns the elapsed time since scheduled playback began.

IsScheduledPlaybackRunning

Determine if the video output scheduler is running

GetHardwareReferenceClock

Get scheduling time

GetReferenceStatus

Provides reference genlock status

IDeckLinkOutput::DoesSupportVideoMode method
The DoesSupportVideoMode method indicates whether a given display mode is supported on output.
Modes may be supported, unsupported or supported with conversion. If the requested video modecannot be output then the video will be converted into a supported video mode indicated by actualMode.

NOTE When using HDMI as an output connection, the DoesSupportVideoMode method does notaccount for the actual supported modes of the connected HDMI sink. To check whether an output
mode will be supported by an HDMI sink, an application can additionally decode the received EDID
obtained by IDeckLinkStatus::GetBytes with status item bmdDeckLinkStatusReceivedEDID.

SyntaxHRESULToesSupportVideoMode (BMDVideoConnection connection,
D
BMDDisplayMode requestedMode, BMDPixelFormat requestedPixelFormat,
BMDVideoOutputConversionMode conversion, BMDSupportedVideoModeFlags flags,
BMDDisplayMode *actualMode, bool *supported);Parameters
Name

Direction

Description

connectionin

Output connection to check (see BMDVideoConnection for details).

requestedModein

Display mode to checkrequestedPixelFormat

in

Pixel format to checkconversionModein

Output conversion mode to check(see BMDVideoOutputConversionMode for details)

flags

in

Output video mode flags (see BMDSupportedVideoModeFlags
for details).

actualModeout

If this parameter is not NULL and the display mode is supported or
supported with conversion, the actual display mode is returned.

supportedout

Pixel format to check

Return Values
Value

Description

E_INVALIDARG

Invalid value for parameters requestedMode or requestedPixelFormat,
or parameter supported variable is NULL.

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API39

2.5.3.2

IDeckLinkOutput::GetDisplayMode method
The GetDisplayMode method returns the IDeckLinkDisplayMode object interface for an output display
mode identifier.
SyntaxHRESULT

etDisplayMode (BMDDisplayMode displayMode,G
IDeckLinkDisplayMode *resultDisplayMode);

Parameters
Name

Direction

Description

displayModein

The display mode ID (See BMDDisplayMode).

resultDisplayMode

out

Pointer to the display mode with matching ID. The object must be
released by the caller when no longer required.

Return Values

2.5.3.3

Value

Description

E_INVALIDARG

Parameter active status variable is NULL

E_FAIL

FailureS_OK

Success

IDeckLinkOutput::IsScheduledPlaybackRunning method
The IsScheduledPlaybackRunning method is called to determine if the driver’s video output scheduler iscurrently active.
SyntaxHRESULTIsScheduledPlaybackRunning (boolean *active)Parameters
Name

Direction

Description

activeout

Active status of driver video output scheduler

Return Values
Value

Description

E_INVALIDARG

Parameter active status variable is NULL

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API40

2.5.3.4

IDeckLinkOutput::GetDisplayModeIterator method
The GetDisplayModeIterator method returns an iterator which enumerates the available display modes.
SyntaxHRESULT

GetDisplayModeIterator (IDeckLinkDisplayModeIterator *iterator);Parameters
Name

Direction

Description

iterator

out

Display mode iterator

Return Values

2.5.3.5

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkOutput::SetScreenPreviewCallback method
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.
SyntaxHRESULT

SetScreenPreviewCallback (IDeckLinkScreenPreviewCallback *previewCallback)Parameters
Name

Direction

Description

previewCallback

in

The IDeckLinkScreenPreview object to be registered.

Return Values
Value

Description

E_OUTOFMEMORY

Unable to create kernel event (Windows only)

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API41

2.5.3.6

IDeckLinkOutput::EnableVideoOutput method
The EnableVideoOutput method enables video output. Once video output is enabled, frames may bedisplayed immediately with DisplayVideoFrameSync or scheduled with ScheduleVideoFrame.
SyntaxHRESULT

EnableVideoOutput (BMDDisplayMode displayMode, BMDVideoOutputFlags flags);
Parameters
Name

Direction

Description

displayMode

in

Display mode for video output

flags

in

Flags to control ancillary data and video output features.

Return Values

2.5.3.7

Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

Unable to access the hardware

E_OUTOFMEMORY

Unable to create a new frame

IDeckLinkOutput::DisableVideoOutput method
The DisableVideoOutput method disables video output.
SyntaxHRESULTDisableVideoOutput ();Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API42

2.5.3.8

IDeckLinkOutput::SetVideoOutputFrameMemoryAllocator method
The SetVideoOutputFrameMemoryAllocator method sets a custom memory allocator for video frame
allocations during playback. The use of a custom memory allocator is optional.
SyntaxHRESULT etVideoOutputFrameMemoryAllocator
S(IDeckLinkMemoryAllocator *theAllocator);

Parameters
Name

Direction

Description

theAllocatorin

Allocator object with an IDeckLinkMemoryAllocator interface

Return Values

2.5.3.9

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkOutput::CreateVideoFrame method
The CreateVideoFrame method creates a video frame for output (see IDeckLinkMutableVideoFrame formore information).
SyntaxHRESULTreateVideoFrame (long width, long height, long rowBytes, BMDPixelFormatCpixelFormat, BMDFrameFlags flags, IDeckLinkMutableVideoFrame *outFrame);

Parameters
Name

Direction

Description

width

in

frame width in pixels

heightinframe height in pixels

rowBytesinbytes per row

pixelFormatinpixel format

flags

in

frame flags

outFrameout

newly created video frame

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

43

2.5.3.10 IDeckLinkOutput::CreateAncillaryData method
The CreateAncillaryData method creates an ancillary buffer that can be attached to an
IDeckLinkMutableVideoFrame.
SyntaxHRESULTreateAncillaryData (BMDPixelFormat pixelFormat,
C
IDeckLinkVideoFrameAncillary* outBuffer);

Parameters
Name

Direction

Description

pixelFormat

in

Pixel format for ancillary data

outBufferout

New video frame ancillary buffer

Return Values

2.5.3.11

Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

Video output is not enabled.

IDeckLinkOutput::DisplayVideoFrameSync method
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.
SyntaxHRESULT

DisplayVideoFrameSync (IDeckLinkVideoFrame *theFrame);Parameters
Name

Direction

Description

theFrameinframe to display – after call return, the frame may be released

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

The video output is not enabled.

E_INVALIDARG

The frame attributes are invalid.

Section 2 — DeckLink API

44

2.5.3.12

IDeckLinkOutput::ScheduleVideoFrame method
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 bescheduled before calling StartScheduledPlayback to preroll. Once playback is initiated, new frames canbe scheduled from IDeckLinkVideoOutputCallback.
SyntaxHRESULTcheduleVideoFrame (IDeckLinkVideoFrame *theFrame,S
BMDTimeValue displayTime, BMDTimeValue displayDuration,
BMDTimeScale timeScale);Parameters
Name

Direction

Description

theFrameinframe to display

displayTime

intime at which to display the frame in timeScale units

displayDurationinduration for which to display the frame in timeScale units

timeScaleintime scale for displayTime and displayDuration

Return Values

2.5.3.13

Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

The video output is not enabled.

E_INVALIDARG

The frame attributes are invalid.

E_OUTOFMEMORY

Too many frames are already scheduled

IDeckLinkOutput::SetScheduledFrameCompletionCallback method
The SetScheduledFrameCompletionCallback method configures a callback which will be called wheneach scheduled frame is completed.
SyntaxHRESULT etScheduledFrameCompletionCallback
S(IDeckLinkVideoOutputCallback *theCallback);Parameters
Name

Direction

Description

theCallBackin

Callback object implementing the IDeckLinkVideoOutputCallback
object interface

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API45

2.5.3.14

IDeckLinkOutput::GetBufferedVideoFrameCount method
The GetBufferedVideoFrameCount method gets the number of frames queued.
SyntaxHRESULT

GetBufferedVideoFrameCount (uint32_t *bufferedFrameCount);Parameters
Name

Direction

Description

bufferedFrameCountout

The frame count.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.3.15 IDeckLinkOutput::EnableAudioOutput method
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 ofscheduled playback using ScheduleAudioSamples.
SyntaxHRESULTnableAudioOutput (BMDAudioSampleRate sampleRate, BMDAudioSampleTypeEsampleType, uint32_t channelCount, BMDAudioOutputStreamType streamType);

Parameters
Name

Direction

Description

sampleRatein

Sample rate to output

sampleTypein

Sample type to output

channelCountin

Number of audio channels to output – only 2, 8, 16, 32 or 64 channel
output is supported.

streamTypeinType of audio output stream.

Return Values
Value

Description

E_FAIL

FailureE_INVALIDARG

Invalid number of channels requested

S_OK

Success

E_ACCESSDENIED

Unable to access the hardware or audio output not enabled.

E_OUTOFMEMORY

Unable to create internal object

Section 2 — DeckLink API46

2.5.3.16 IDeckLinkOutput::DisableAudioOutput method
The DisableAudioOutput method disables the hardware audio output mode.
SyntaxHRESULTDisableAudioOutput ();Parameters
none.
Return Values

2.5.3.17

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkOutput::WriteAudioSamplesSync method
The WriteAudioSamplesSync method is used to play audio sample frames immediately. Audio output
must be configured with EnableAudioOutput. WriteAudioSamplesSync should not be called duringscheduled playback.
SyntaxHRESULTriteAudioSamplesSync (void *buffer, uint32_t sampleFrameCount,Wuint32_t *sampleFramesWritten);Parameters
Name

Direction

Description

bufferin

Buffer containing audio sample frames. Audio channel samples must be
interleaved into a sample frame and sample frames must be contiguous.

sampleFrameCountin

Number of sample frames available

sampleFramesWritten

out

Actual number of sample frames queued

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API47

2.5.3.18

IDeckLinkOutput::BeginAudioPreroll method
The BeginAudioPreroll method requests the driver begin polling the registered
IDeckLinkAudioOutputCallback::RenderAudioSamples object interface for audio-preroll.
SyntaxHRESULTBeginAudioPreroll ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.3.19 IDeckLinkOutput::EndAudioPreroll method
The EndAudioPreroll method requests the driver stop polling the registered IDeckLinkAudioOutputCallback
object interface for audio-preroll.
SyntaxHRESULTEndAudioPreroll ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API48

2.5.3.20 IDeckLinkOutput::ScheduleAudioSamples method
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.

NOTE When the output parameter sampleFramesWritten is NULL, ScheduleAudioSamples will block
until all audio samples are written to the scheduling buffer. If the sampleFramesWritten parameter is
non-NULL, the call to ScheduleAudioSamples is non-blocking. In this case, the sampleFramesWritten
output value reflects the actual number of samples written to the scheduling buffer which may be lessthan the parameter sampleFrameCount.

SyntaxHRESULTcheduleAudioSamples (void *buffer, uint32_t sampleFrameCount, BMDTimeValueS
streamTime, BMDTimeScale timeScale, uint32_t *sampleFramesWritten);Parameters
Name

Direction

Description

bufferin

Buffer containing audio sample frames. Audio channel samples must be
interleaved into a sample frame and sample frames must be contiguous.

sampleFrameCountin

Number of sample frames available
Time for audio playback in units of timeScale.
To queue samples to play back immediately after currently bufferedsamples both streamTime and timeScale may be set to zero whenusing bmdAudioOutputStreamContinuous.

streamTime

intimeScaleinTime scale for the audio stream.

sampleFramesWritten

out

Actual number of sample frames scheduled

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

Either audio output has not been enabled or an audio sample write is in progress.

E_INVALIDARG

No timescale has been provided. A timescale is necessary as the audio packets aretime-stamped.

Section 2 — DeckLink API49

2.5.3.21 IDeckLinkOutput::GetBufferedAudioSampleFrameCount method
The 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.
SyntaxHRESULT

GetBufferedAudioSampleFrameCount (uint32_t *bufferedSampleFrameCount)Parameters
Name

Direction

Description

bufferedSampleFrameCountout

Number of audio frames currently buffered.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.3.22 IDeckLinkOutput::FlushBufferedAudioSamples method
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.
SyntaxHRESULTFlushBufferedAudioSamples ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API50

2.5.3.23 IDeckLinkOutput::SetAudioCallback method
The SetAudioCallback method configures a callback which will be called regularly to allow the application
to queue audio for scheduled playback.

TIP Use of this method is optional – audio may alternately be queued
from IDeckLinkVideoOutputCallback::ScheduledFrameCompleted.

SyntaxHRESULT

SetAudioCallback (IDeckLinkAudioOutputCallback *theCallback);Parameters
Name

Direction

Description

theCallBackin

Callback object implementing the IDeckLinkAudioOutputCallback
object interface

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.3.24 IDeckLinkOutput::StartScheduledPlayback method
The StartScheduledPlayback method starts scheduled playback. Frames may be pre-rolled byscheduling them before starting playback. SetScheduledFrameCompletionCallback may be used toregister a callback to be called when each frame is completed.
Scheduled playback starts immediately when StartScheduledPlayback is called, setting the current scheduler
time to the playbackStartTime parameter. Scheduled frames are output as the current scheduler time reaches thescheduled frame’s display time.
SyntaxHRESULTtartScheduledPlayback (BMDTimeValue playbackStartTime,S
BMDTimeScale timeScale, double playbackSpeed);Parameters
Name

Direction

Description

playbackStartTimeinTime at which the playback starts in units of timeScaletimeScaleinTime scale for playbackStartTime and playbackSpeed.

playbackSpeedin

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.

Section 2 — DeckLink API

51

Return Values
Value

Description

E_INVALIDARG

Either parameters playbackStartTime or timeScale are invalid

E_ACCESSDENIED

The video output is not enabled

E_FAIL

FailureS_OK

Success

2.5.3.25 IDeckLinkOutput::StopScheduledPlayback method
The StopScheduledPlayback method stops scheduled playback immediately or at a specified time. Any
frames or audio scheduled after the stop time will be flushed.
SyntaxHRESULTtopScheduledPlayback (BMDTimeValue stopPlaybackAtTime,S
BMDTimeValue *actualStopTime, BMDTimeScale timeScale);Parameters
Name

Direction

Description

stopPlaybackAtTimeinPlayback time at which to stop in units of timeScale. Specify 0 to stop
immediately.

actualStopTimeout

Playback time at which playback actually stopped in units of timeScale.
Specify NULL to stop immediately

timeScaleinTime scale for stopPlaybackAtTime and actualStopTime. Specify 0 tostop immediately.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.3.26 IDeckLinkOutput::GetScheduledStreamTime method
The GetScheduledStreamTime method returns the elapsed time since scheduled playback began.
SyntaxHRESULTetScheduledStreamTime (BMDTimeScale desiredTimeScale,G
BMDTimeValue *streamTime, double *playbackSpeed);Parameters
Name

Direction

Description

desiredTimeScaleinTime scale for elapsedTimeSinceSchedulerBegan

streamTime

out

Frame time

playbackSpeed

out

Scheduled playback speed

Section 2 — DeckLink API

52

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

Video output is not enabled

2.5.3.27 IDeckLinkOutput::GetReferenceStatus method
The GetReferenceStatus method provides the genlock reference status of the DeckLink device.
SyntaxHRESULT

GetReferenceStatus (BMDReferenceStatus *referenceStatus)Parameters
Name

Direction

Description

referenceStatusout

A bit-mask of the reference status.
(See BMDReferenceStatus for more details).

Return Values
Value

Description

E_FAIL

FailureE_POINTER

The parameter is invalid.

S_OK

Success

2.5.3.28 IDeckLinkOutput::GetHardwareReferenceClock method
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).
SyntaxHRESULT

etHardwareReferenceClock (BMDTimeScale desiredTimeScale,G
BMDTimeValue *hardwareTime, BMDTimeValue *timeInFrame,
BMDTimeValue *ticksPerFrame);

Parameters
Name

Direction

Description

desiredTimeScalein

Desired time scale

hardwareTime

out

Hardware reference time (in units of desiredTimeScale)timeInFrame

out

Time in frame (in units of desiredTimeScale)ticksPerFrame

out

Number of ticks for a frame (in units of desiredTimeScale)

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API53

2.5.3.29 IDeckLinkOutput::GetFrameCompletionReferenceTimestamp method
The GetFrameCompletionReferenceTimestamp method is called to determine the time that the frame
has been output. The method outputs a timestamp that is locked to the system clock.
The timestamp is valid if this method is called within the ScheduledFrameCompleted callback and if theframe referenced by the Frame pointer has not been re-scheduled.
SyntaxHRESULTetFrameCompletionReferenceTimestamp (IDeckLinkVideoFrame *theFrame,
G
BMDTimeScale desiredTimeScale, BMDTimeValue *frameCompletionTimestamp)

Parameters
Name

Direction

Description

theFramein

The video frame

desiredTimeScalein

Desired timescale

frameCompletionTimestampoutTimestamp that the frame completed (in units of desiredTimeScale).

Return Values

2.5.4

Value

Description

E_UNEXPECTED

A timestamp for the specified frame is not available.

S_OK

Success

IDeckLinkInput Interface
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. If QueryInterface
for an input interface is called on an output only device, then QueryInterface will fail and return E_NOINTERFACE.
Video capture operates in a push model with each video frame being delivered to an IDeckLinkInputCallback object
interface. Audio capture is optional and can be handled by using the same callback.

NOTE Non-4K DeckLink devices and sub-devices are half-duplex. Therefore either capture or rendercan be enabled, but not simultaneously.

Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkInput object interface may be obtained from
IDeckLink using QueryInterface

IDeckLinkDisplayModeIterator

IID_IDeckLink
DisplayModeIterator

IDeckLinkInput::GetDisplayModeIterator returns an
IDeckLinkDisplayModeIterator object interface

IDeckLinkInputCallback

IID_IDeckLinkInputCallback

An IDeckLinkInputCallback object interface may beregistered with IDeckLinkInput::SetCallback

IDeckLinkDisplayMode

IID_IDeckLinkDisplayMode

IDeckLinkInput::GetDisplayMode returns an
IDeckLinkDisplayMode interface object

Section 2 — DeckLink API

54

Public Member Functions
MethodDescription

DoesSupportVideoMode

Check whether a given video mode is supported for input

GetDisplayModeGet a display mode object based on identifier

GetDisplayModeIterator

Get an iterator to enumerate the available input display modes

SetScreenPreviewCallback

Register screen preview callback

EnableVideoInput

Configure video input

GetAvailableVideoFrameCount

Query number of available video frames

DisableVideoInput

Disable video input

EnableAudioInput

Configure audio input

DisableAudioInput

Disable audio input

GetAvailableAudioSampleFrameCount

Query the buffered audio sample frame countStartStreams

Start synchronized capture

StopStreams

Stop synchronized capture

PauseStreams

Pause synchronized capture

FlushStreams

Removes any buffered video and audio frames.

SetCallback

Register input callback

GetHardwareReferenceClockGet the hardware system clock

SetVideoInputFrameMemoryAllocator

Register custom memory allocator for input video frames

Section 2 — DeckLink API55

2.5.4.1

IDeckLinkInput::DoesSupportVideoMode method
The DoesSupportVideoMode method indicates whether a given display mode is supported on input.
SyntaxHRESULToesSupportVideoMode (BMDVideoConnection connection, BMDDisplayModeD
requestedMode, BMDPixelFormat requestedPixelFormat,
BMDVideoInputConversionMode conversion, BMDSupportedVideoModeFlags flags,bool *supported);Parameters
Name

Direction

Description

connection

in

Input connection to check (see BMDVideoConnection for details).

requestedModein

Display mode to checkrequestedPixelFormat

in

Pixel format to checkconversionMode

in

Input conversion mode to check(see BMDVideoInputConversionMode for details)

flags

in

Input video mode flags(see BMDSupportedVideoModeFlags for details).

actualModeout

If this parameter is not NULL and the display mode is supported or
supported with conversion, the actual display mode is returned.

supportedout

Returns true if the display mode is supported.

Return Values
Value

Description

E_INVALIDARG

Either parameter requestedMode has an invalid value or parameter
supported variable is NULL.

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

56

2.5.4.2

IDeckLinkInput::GetDisplayMode method
The GetDisplayMode method returns the IDeckLinkDisplayMode object interface for an input display mode identifier.
SyntaxHRESULT

etDisplayMode (BMDDisplayMode displayMode,G
IDeckLinkDisplayMode *resultDisplayMode);

Parameters
Name

Direction

Description

displayModein

The display mode ID (See BMDDisplayMode)

resultDisplayMode

out

Pointer to the display mode with matching ID. The object must be
released by the caller when no longer required.

Return Values

2.5.4.3

Value

Description

E_INVALIDARG

Either parameter displayMode has an invalid value or parameter
resultDisplayMode variable is NULL.

E_OUTOFMEMORY

Insufficient memory to create the result display mode object.

S_OK

Success

IDeckLinkInput::GetDisplayModeIterator method
The GetDisplayModeIterator method returns an iterator which enumerates the available display modes.
SyntaxHRESULT

GetDisplayModeIterator(IDeckLinkDisplayModeIterator** iterator)

Parameters
Name

Direction

Description

iterator

out

Display mode iterator

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

57

2.5.4.4

IDeckLinkInput::SetScreenPreviewCallback method
The SetScreenPreviewCallback method is called to register an instance of an
IDeckLinkScreenPreviewCallback object. The registered object facilitates the updatingof an on-screen preview of a video stream being captured.
SyntaxHRESULT

SetScreenPreviewCallback (IDeckLinkScreenPreviewCallback *previewCallback)Parameters
Name

Direction

Description

previewCallback

in

The IDeckLinkScreenPreview object to be registered.

Return Values

2.5.4.5

Value

Description

S_OK

Success

IDeckLinkInput::EnableVideoInput method
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.
SyntaxHRESULTnableVideoInput (BMDDisplayMode displayMode,
E
BMDPixelFormat pixelFormat, BMDVideoInputFlags flags);

Parameters
Name

Direction

Description

displayModeinVideo mode to capture

pixelFormat

in

Pixel format to capture

flags

in

Capture flags

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

Is returned on invalid mode or video flags

E_ACCESSDENIED

Unable to access the hardware or input stream currently active

E_OUTOFMEMORY

Unable to create a new frame

Section 2 — DeckLink API

58

2.5.4.6

IDeckLinkInput::GetAvailableVideoFrameCount method
The GetAvailableVideoFrameCount method provides the number of available input frames.
SyntaxHRESULT

GetAvailableVideoFrameCount (uint32_t *availableFrameCount);Parameters
Name

Direction

Description

availableFrameCountout

Number of available input frames.

Return Values

2.5.4.7

Value

Description

S_OK

Success

IDeckLinkInput::DisableVideoInput method
The DisableVideoInput method disables the hardware video capture mode.
SyntaxHRESULTDisableVideoInput ();Parameters
none.
Return Values

2.5.4.8

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkInput::EnableAudioInput method
The EnableAudioInput method configures audio input and puts the hardware into audio capture mode.
Synchronized audio and video input is started by calling StartStreams.
SyntaxHRESULTnableAudioInput (BMDAudioSampleRate sampleRate,
E
BMDAudioSampleType sampleType, uint32_t channelCount);

Parameters
Name

Direction

Description

sampleRatein

Sample rate to capture

sampleTypein

Sample type to capturechannelCountin

Number of audio channels to capture – only 2, 8, 16, 32 or 64 channel
capture is supported.

Section 2 — DeckLink API

59

Return Values

2.5.4.9

Value

Description

E_FAIL

FailureE_INVALIDARG

Invalid number of channels requested

S_OK

Success

IDeckLinkInput::DisableAudioInput method
The DisableAudioInput method disables the hardware audio capture mode.
SyntaxHRESULTDisableAudioInput ();Parameters
none.
Return Values

2.5.4.10

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkInput::GetAvailableAudioSampleFrameCount method
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.
SyntaxHRESULT etAvailableAudioSampleFrameCountG(uint32_t *availableSampleFrameCount);

Parameters
Name

Direction

Description

availableSampleFrameCountout

The number of buffered audio frames currently available.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API60

2.5.4.11

IDeckLinkInput::SetVideoInputFrameMemoryAllocator method
The SetVideoInputFrameMemoryAllocator method sets a custom memory allocator for video frame
allocations during capture. Use of a custom memory allocator is optional.
SyntaxHRESULT etVideoInputFrameMemoryAllocator
S(IDeckLinkMemoryAllocator *theAllocator);

Parameters
Name

Direction

Description

theAllocatorin

Allocator object with an IDeckLinkMemoryAllocator interface

Return Values

2.5.4.12

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkInput::StartStreams method
The StartStreams method starts synchronized video and audio capture as configured with
EnableVideoInput and optionally EnableAudioInput.
SyntaxHRESULT

StartStreams ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

Input stream is already running.

E_UNEXPECTED

Video and Audio inputs are not enabled.

Section 2 — DeckLink API

61

2.5.4.13

IDeckLinkInput::StopStreams method
The StopStreams method stops synchronized video and audio capture.
SyntaxHRESULTStopStreams ();Parameters
none.
Return Values

2.5.4.14

Value

Description

S_OK

Success

E_ACCESSDENIED

Input stream already stopped.

IDeckLinkInput::FlushStreams method
The FlushStreams method removes any buffered video and audio frames.
SyntaxHRESULTFlushStreams ();Parameters
none.
Return Values

2.5.4.15

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkInput::PauseStreams method
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 bycalling PauseStreams again. Capture may also be resumed by calling StartStreams but capture time
will be reset.
SyntaxHRESULTPauseStreams ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API62

2.5.4.16

IDeckLinkInput::SetCallback method
The SetCallback method configures a callback which will be called for each captured frame. Synchronizedcapture is started with StartStreams, stopped with StopStreams and may be paused with PauseStreams.
SyntaxHRESULT

SetCallback (IDeckLinkInputCallback *theCallback);Parameters
Name

Direction

Description

theCallBackincallback object implementing the IDeckLinkInputCallback object
interface

Return Values

2.5.4.17

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkInput::GetHardwareReferenceClock method
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 isenabled (see IDeckLinkInput::EnableVideoInput for details).
SyntaxHRESULT

etHardwareReferenceClock (BMDTimeScale desiredTimeScale, BMDTimeValueG*hardwareTime, BMDTimeValue *timeInFrame, BMDTimeValue *ticksPerFrame);

Parameters
Name

Direction

Description

desiredTimeScalein

Desired time scale

hardwareTime

out

Hardware reference time (in units of desiredTimeScale)timeInFrame

out

Time in frame (in units of desiredTimeScale)ticksPerFrame

out

Number of ticks for a frame(in units of desiredTimeScale)

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

63

2.5.5

IDeckLinkVideoFrame Interface
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.

TIP Developers may sub-class IDeckLinkVideoFrame to provide an implementation which fits wellwith their application’s structure.

Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrame
3DExtensions

IID_IDeckLinkVideoFrame
3DExtensions

An IDeckLinkVideoFrame3DExtensions
object interface may be obtained from
IDeckLinkVideoFrame using QueryInterface

IDeckLinkGLScreen
PreviewHelper

IID_IDeckLinkGLScreen
PreviewHelper

An IDeckLinkVideoFrame object
interface is set for OpenGL preview with
IDeckLinkGLScreenPreviewHelper::SetFrame

IDeckLinkDX9Screen
PreviewHelper

IID_IDeckLinkDX9Screen
PreviewHelper

An IDeckLinkVideoFrame object
interface is set for DirectX preview with
IDeckLinkDX9ScreenPreviewHelper::SetFrame

IDeckLinkVideoOutputCallback

IID_
IDeckLinkVideoOutputCallback

An IDeckLinkVideoFrame object interface is passed
to IDeckLinkVideoOutputCallback::Scheduled
FrameCompleted

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkVideoFrame object
interface is displayed synchronously with
IDeckLinkOutput::DisplayVideoFrameSync

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkVideoFrame object
interface is scheduled for playback with
IDeckLinkOutput::ScheduleVideoFrame

IDeckLinkVideoFrame
AncillaryPackets

IID_IDeckLinkVideoFrame
AncillaryPackets

An IDeckLinkVideoFrameAncillaryPackets
object interface may be obtained from
IDeckLinkVideoFrame using QueryInterface

IDeckLinkMutableVideoFrame

IID_
IDeckLinkMutableVideoFrame

IDeckLinkMutableVideoFrame subclasses
IDeckLinkVideoFrame

IDeckLinkMetalScreen
PreviewHelper

IID_IDeckLinkMetalScreen
PreviewHelper

An IDeckLinkVideoFrame object
interface is set for Metal preview with
IDeckLinkMetalScreenPreviewHelper::SetFrame

IDeckLinkVideoFrame
MetadataExtensions

IID_IDeckLinkVideoFrame
MetadataExtensions

An IDeckLinkVideoFrameMetadataExtensions
object interface may be obtained from
IDeckLinkVideoFrame using QueryInterface

IDeckLinkVideoFrameAncillary

IID_
IDeckLinkVideoFrameAncillary

IDeckLinkVideoFrame::GetAncillaryData outputs an
IDeckLinkVideoFrameAncillary object interface

IDeckLinkVideoInputFrameIID_IDeckLinkVideoInputFrame

IDeckLinkVideoInputFrame subclasses
IDeckLinkVideoFrame

IDeckLinkWPFDX9Screen
PreviewHelper

IID_IDeckLinkWPFDX9Screen
PreviewHelper

An IDeckLinkVideoFrame object
interface is set for DirectX preview with
IDeckLinkWPFDX9ScreenPreviewHelper::SetFrame

IDeckLinkTimecode

IID_IDeckLinkTimecode

IDeckLinkVideoFrame::GetTimecode outputs an
IDeckLinkTimecode object interface

Section 2 — DeckLink API

64

IDeckLinkScreenPreviewCallback

IID_
IDeckLinkScreenPreviewCallback

An IDeckLinkVideoFrame object
interface is provided for rendering by
IDeckLinkScreenPreviewCallback::DrawFrame

IDeckLinkVideoConversion

IID_IDeckLinkVideoConversion

An IDeckLinkVideoFrame object
interface is the source video frame for
IDeckLinkVideoConversion::ConvertFrame

IDeckLinkVideoConversion

IID_IDeckLinkVideoConversion

An IDeckLinkVideoFrame object
interface is the destination video frame for
IDeckLinkVideoConversion::ConvertFrame

Public Member Functions

2.5.5.1

MethodDescription

GetWidth

Get video frame width in pixels

GetHeight

Get video frame height in pixels

GetRowBytes

Get bytes per row for video frame

GetPixelFormat

Get pixel format for video frame

GetFlags

Get frame flags

GetBytes

Get pointer to frame data

GetTimecode

Gets timecode information

GetAncillaryData

Gets ancillary data

IDeckLinkVideoFrame::GetWidth method
The GetWidth method returns the width of a video frame.
Syntaxlong

GetWidth ();Return Values

2.5.5.2

Value

Description

WidthVideo frame width in pixels

IDeckLinkVideoFrame::GetHeight method
The GetHeight method returns the height of a video frame.
Syntaxlong

GetHeight ();Return Values
Value

Description

HeightVideo frame height in pixels

Section 2 — DeckLink API65

2.5.5.3

IDeckLinkVideoFrame::GetRowBytes method
The GetRowBytes method returns the number of bytes per row of a video frame.
Syntaxlong

GetRowBytes ();Return Values

2.5.5.4

Value

Description

BytesCount

Number of bytes per row of video frame

IDeckLinkVideoFrame::GetPixelFormat method
The GetPixelFormat method returns the pixel format of a video frame.
Syntax

BMDPixelFormat

GetPixelFormat ();Return Values

2.5.5.5

Value

Description

PixelFormat

Pixel format of video frame (BMDPixelFormat)

IDeckLinkVideoFrame::GetFlags method
The GetFlags method returns status flags associated with a video frame.
SyntaxBMDFrameFlags

GetFlags ();Return Values

2.5.5.6

Value

Description

FrameFlags

Video frame flags (BMDFrameFlags)

IDeckLinkVideoFrame::GetBytes method
The GetBytes method allows direct access to the data buffer of a video frame.
SyntaxHRESULT

GetBytes (void **buffer);Parameters
Name

Direction

Description

bufferout

Pointer to raw frame buffer – only valid while object remains valid.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API66

2.5.5.7

IDeckLinkVideoFrame::GetTimecode method
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.
SyntaxHRESULT

GetTimecode (BMDTimecodeFormat format, IDeckLinkTimecode *timecode)Parameters
Name

Direction

Description

formatin

BMDTimecodeFormat to query

timecode

out

Pointer to IDeckLinkTimecode interface object containing therequested timecode or NULL if requested timecode is not available.
This object must be released by the caller when no longer required.

Return Values

2.5.5.8

Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

An invalid or unsupported timecode format was requested.

S_FALSEThe requested timecode format was not present or valid in the
ancillary data.

IDeckLinkVideoFrame::GetAncillaryData method
The GetAncillaryData method returns a pointer to a video frame’s ancillary data.
SyntaxHRESULT

GetAncillaryData (IDeckLinkVideoFrameAncillary *ancillary)

Parameters
Name

Direction

Description

ancillaryout

Pointer to a new IDeckLinkVideoFrameAncillary object. This object
must be released by the caller when no longer required.

Return Values

2.5.6

Value

Description

S_OK

Success

S_FALSENo ancillary data present.

IDeckLinkVideoOutputCallback Interface
The IDeckLinkVideoOutputCallback object interface is a callback class which is called for each frame asits 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 areplacement frame to maintain streaming playback. If the application is managing its own frame buffers,
they should be disposed or reused inside the ScheduledFrameCompleted callback.

Section 2 — DeckLink API

67

Related Interfaces
Interface

Interface ID

Description

IDeckLinkOutput

IID_IDeckLinkOutput

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

Public Member Functions

2.5.6.1

MethodDescription

ScheduledFrameCompleted

Called when playback of a scheduled frame is completed

ScheduledPlaybackHasStopped

Called when playback has stopped.

IDeckLinkVideoOutputCallback::ScheduledFrameCompleted method
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 aframe time, multiple threads should be used.
SyntaxHRESULTcheduledFrameCompleted (IDeckLinkVideoFrame* completedFrame,S
BMDOutputFrameCompletionResult result);

Parameters
Name

Direction

Description

completedFramein

Completed frame

resultin

Frame completion result(see BMDOutputFrameCompletionResult for details).

Return Values

2.5.6.2

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkVideoOutputCallback::ScheduledPlaybackHasStopped method
The ScheduledPlaybackHasStopped method is called when a scheduled playback has stopped.
SyntaxHRESULTScheduledPlaybackHasStopped(void)

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

68

2.5.7

IDeckLinkMutableVideoFrame Interface
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 iscreated by the IDeckLinkOutput::CreateVideoFrame method.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

IDeckLinkMutableVideoFrame subclasses
IDeckLinkVideoFrame

Public Member Functions

2.5.7.1

MethodDescription

SetFlags

Set flags applicable to a video frame

SetTimecode

Set timecode

SetTimecodeFromComponents

Set components of specified timecode type

SetAncillaryData

Set frame ancillary data

SetTimecodeUserBits

Set the timecode user bits

IDeckLinkMutableVideoFrame::SetFlags method
The SetFlags method sets output flags associated with a video frame.
SyntaxHRESULT

SetFlags (BMDFrameFlags newFlags);
Parameters
Name

Direction

Description

newFlags

in

BMDFrameFlags to set see BMDFrameFlags for details.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API69

2.5.7.2

IDeckLinkMutableVideoFrame::SetTimecode method
The SetTimecode method sets the specified timecode type for the frame.
SyntaxHRESULT

SetTimecode (BMDTimecodeFormat format, IDeckLinkTimecode* timecode);Parameters
Name

Direction

Description

formatin

BMDTimecodeFormat to update

timecodein

IDeckLinkTimecode object interface containing timecode to copy.

Return Values

2.5.7.3

Value

Description

E_UNEXPECTED

Unexpected timecode. Ensure that VITC1 has been set.

S_OK

Success

IDeckLinkMutableVideoFrame::SetTimecodeFromComponents method
The SetTimecodeFromComponents method sets the components of the specified
timecode type for the frame.
SyntaxHRESULT

etTimecodeFromComponents (BMDTimecodeFormat format, uint8_t hours,S
uint8_t minutes, uint8_t seconds, uint8_t frames, BMDTimecodeFlags flags);

Parameters
Name

Direction

Description

formatin

BMDTimecodeFormat to update

hours

in

Value of hours component of timecode

minutesinValue of minutes component of timecode

seconds

inValue of seconds component of timecode

framesinValue of frames component of timecode

flags

in

Timecode flags (see BMDTimecodeFlags for details)

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API70

2.5.7.4

IDeckLinkMutableVideoFrame::SetAncillaryData method
The SetAncillaryData method sets frame ancillary data. An IDeckLinkVideoFrameAncillary may becreated using the IDeckLinkOutput::CreateAncillaryData method.
SyntaxHRESULT

SetAncillaryData (IDeckLinkVideoFrameAncillary* ancillary);Parameters
Name

Direction

Description

ancillaryin

IDeckLinkVideoFrameAncillary data to output with the frame.

Return Values

2.5.7.5

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkMutableVideoFrame::SetTimecodeUserBits method
The SetTimecodeUserBits method sets the timecode user bits.
SyntaxHRESULT

etTimecodeUserBits (BMDTimecodeFormat format,
S
BMDTimecodeUserBits userBits)

Parameters
Name

Direction

Description

formatin

The format of the timecode.

userBitsin

The user bits to set.

Return Values
Value

Description

E_NOTIMPL

Not implemented

E_INVALIDARG

The format parameter is invalid.

E_UNEXPECTED

Timecode object is not present.
(See: IDeckLinkMutableVideoFrame::SetTimecode)

Section 2 — DeckLink API71

2.5.8

IDeckLinkVideoFrame3DExtensions Interface
The IDeckLinkVideoFrame3DExtensions interface allows linking of video frames in left eye / right eye
pairs, to support 3D capture and playback.

NOTE This interface is applicable only to DeckLink devices which support 3D features, such the
DeckLink 4K Extreme.
All frames belonging to a 3D stream carry an IDeckLinkVideoFrame3DExtensions object, which indicates
whether this frame is a left or right-eye frame and allows access to the right eye frame if this frame is a left
eye frame.
To output in 3D video mode, IDeckLinkOutput::EnableVideoOutput is called with video output flag
bmdVideoOutputDualStream3D. The application must provide video frame objects which implement
both the IDeckLinkVideoFrame and IDeckLinkVideoFrame3DExtensions interfaces.
To capture a 3D signal, IDeckLinkInput::EnableVideoInput is called with video input flag
bmdVideoInputDualStream3D. An IDeckLinkVideoFrame3DExtensions object can be obtained from
IDeckLinkVideoInputFrame using QueryInterface.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

An IDeckLinkVideoFrame3DExtensions object interface
may be obtained from IDeckLinkVideoFrame using
QueryInterface

Public Member Functions

2.5.8.1

MethodDescription

Get3DPackingFormat

The indication of whether the frame represents the left or theright eye.

GetFrameForRightEye

Get the right eye frame of a 3D pair.

IDeckLinkVideoFrame3DExtensions::Get3DPackingFormat method
The Get3DPackingFormat method indicates whether the video frame belongs to the left eyeor right eye stream.
SyntaxBMDVideo3DPackingFormatGet3DPackingFormat (void)

Return Values
Value

Description

Packing format

Either bmdVideo3DPackingRightOnly or
bmdVideo3DPackingLeftOnly.
See BMDVideo3DPackingFormat for more details.

Section 2 — DeckLink API72

2.5.8.2

IDeckLinkVideoFrame3DExtensions::GetFrameForRightEye method
The GetFrameForRightEye method accesses the right eye frame of a 3D pair.
SyntaxHRESULT

GetFrameForRightEye (IDeckLinkVideoFrame* *rightEyeFrame)Parameters
Name

Direction

Description

rightEyeFrameout

The right eye frame. This object must be released by the caller when nolonger required.

Return Values

2.5.9

Value

Description

E_INVALIDARG

The parameter is invalid.

S_FALSEThis frame is the right eye frame.

S_OK

Success

IDeckLinkAudioOutputCallback Interface
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

Interface ID

Description

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkAudioOutputCallback object interface may beregistered with IDeckLinkOutput::SetAudioCallback

Public Member Functions
MethodDescription

RenderAudioSamples

Called to allow buffering of more audio samples if required

Section 2 — DeckLink API73

2.5.9.1

IDeckLinkAudioOutputCallback::RenderAudioSamples method
The RenderAudioSamples method is called at a rate of 50Hz during playback. When audio preroll isenabled with a call to IDeckLinkOutput::BeginAudioPreroll.
During preroll (preroll is TRUE) call IDeckLinkOutput::ScheduleAudioSamples to schedule sufficient
audio samples for the number of video frames that have scheduled.
During playback (preroll is FALSE) check the count of buffered audio samples with
IDeckLinkOutput::GetBufferedAudioSampleFrameCount and when required, schedule more audio
samples with IDeckLinkOutput::ScheduleAudioSamples.
SyntaxHRESULTRenderAudioSamples (boolean preroll);Parameters
Name

Direction

Description

prerollinFlag specifying whether driver is currently pre-rolling (TRUE)
or playing (FALSE).

Return Values

2.5.10Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkInputCallback Interface
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

Interface ID

Description

IDeckLinkInput

IID_IDeckLinkInput

An IDeckLinkInputCallback object interface may beregistered with IDeckLinkInput::SetCallback

IDeckLinkVideoInputFrameIID_
DeckLinkVideoInputFrame

An IDeckLinkVideoInputFrame object interface is passed
to IDeckLinkInputCallback::VideoInputFrameArrived

IDeckLinkAudioInputPacket

IID_
DeckLinkAudioInputPacket

An IDeckLinkAudioInputPacket object interface is passed
to IDeckLinkInputCallback::VideoInputFrameArrived

Public Member Functions
MethodDescription

VideoInputFrameArrived

Called when new video data is available

VideoInputFormatChanged

Called when a video input format change is detected

Section 2 — DeckLink API74

2.5.10.1

IDeckLinkInputCallback::VideoInputFrameArrived method
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.
SyntaxHRESULTideoInputFrameArrived (IDeckLinkVideoInputFrame *videoFrame,V
IDeckLinkAudioInputPacket *audioPacket);Parameters
Name

Direction

Description
The video frame that has arrived. The video frame is only valid for theduration of the callback.
To hold on to the video frame beyond the callback call AddRef, andto release the video frame when it is no longer required call Release.

videoFramein

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.
New audio packet-only valid if audio capture has been enabled with
IDeckLinkInput::EnableAudioInput

audioPacket

in

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

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API75

2.5.10.2 IDeckLinkInputCallback::VideoInputFormatChanged method
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 whencalling 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 IDeckLinkProfileAttributes Interface for details).

SyntaxHRESULT	VideoInputFormatChanged (BMDVideoInputFormatChangedEvents notificationEvents,
IDeckLinkDisplayMode *newDisplayMode, BMDDetectedVideoInputFormatFlags
detectedSignalFlags);
Parameters
Name

Direction

Description

notificationEventsinThe notification events enable input detection

newDisplayModein

The new display mode.

detectedSignalFlags

in

The detected signal flags

Return Values

2.5.11

Value

Description

E_FAIL

FailureS_OK

Success

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

Interface ID

Description

IDeckLinkInput

IID_IDeckLinkInput

New input frames are returned to
IDeckLinkInputCallback::VideoInputFrameArrived by the
IDeckLinkInput interface

IDeckLinkVideoFrame

IID_
IDeckLinkVideoFrame

IDeckLinkVideoInputFrame subclasses IDeckLinkVideoFrame

Public Member Functions
MethodDescription

GetStreamTime

Get video frame timing information

GetHardwareReferenceTimestamp

Get hardware reference timestamp

Section 2 — DeckLink API76

2.5.11.1

IDeckLinkVideoInputFrame::GetStreamTime method
The GetStreamTime method returns the time and duration of a captured video frame fora given timescale.
SyntaxHRESULT etStreamTime (BMDTimeValue *frameTime,G
BMDTimeValue *frameDuration, BMDTimeScale timeScale);Parameters
Name

Direction

Description

frameTimeout

Frame time (in units of timeScale)frameDurationout

Frame duration (in units of timeScale)timeScaleinTime scale for output parameters

Return Values

2.5.11.2

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkVideoInputFrame::GetHardwareReferenceTimestamp method
The GetHardwareReferenceTimestamp method returns frame time and frame duration for a given
timescale.
SyntaxHRESULT

etHardwareReferenceTimestamp (BMDTimeScale timeScale,G
BMDTimeValue *frameTime, BMDTimeValue *frameDuration);

Parameters
Name

Direction

Description

timeScalein

The time scale see BMDTimeScale for details.

frameTimeout

The frame time see BMDTimeValue for details.

frameDurationout

The frame duration see BMDTimeValue for details.

Return Values
Value

Description

E_INVALIDARG

Timescale is not set

S_OK

Success

Section 2 — DeckLink API77

2.5.12

IDeckLinkAudioInputPacket Interface
The IDeckLinkAudioInputPacket object interface represents a packet of audio which has been capturedby 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

Interface ID

Description

IDeckLinkInputCallback

IID_IDeckLinkInputCallback

New audio packets are returned to the
IDeckLinkInputCallback::VideoInputFrameArrived callback

Public Member Functions

2.5.12.1

MethodDescription

GetSampleFrameCountGet number of sample frames in packet

GetBytes

Get pointer to raw audio frame sequence

GetPacketTime

Get corresponding video timestamp

IDeckLinkAudioInputPacket::GetSampleFrameCount method
The GetSampleFrameCount method returns the number of sample frames in the packet.
Syntaxlong 	GetSampleFrameCount ();Return Values

2.5.12.2

Value

Description

Count

Audio packet size in sample frames

IDeckLinkAudioInputPacket::GetBytes method
The GetBytes method returns a pointer to the data buffer of the audio packet.
SyntaxHRESULT

GetBytes (void *buffer);Parameters
Name

Direction

Description

bufferout

pointer to audio data – only valid while object remains valid

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API78

2.5.12.3

IDeckLinkAudioInputPacket::GetPacketTime method
The GetPacketTime method returns the time stamp of the video frame corresponding to the specified audio packet.
SyntaxHRESULT

GetPacketTime (BMDTimeValue *packetTime, BMDTimeScale timeScale);Parameters
Name

Direction

Description

packetTime

out

Video frame time corresponding to audio packet in timeScale units

timeScaleinTime scale for time stamp to be returned

Return Values

2.5.13

Value

Description

E_FAIL

FailureS_OK

Success

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

NOTE The IDeckLinkDisplayModeIterator will enumerate all display modes regardless of the current
profile. An application should call the DoesSupportVideoMode method in the IDeckLinkInput,
IDeckLinkOutput or IDeckLinkEncoderInput interfaces to ensure that a display mode is supported
for a given profile.

Interface

Interface ID

Description

IDeckLinkInput

IID_IDeckLinkInput

IDeckLinkInput::GetDisplayModeIterator returns an
IDeckLinkDisplayModeIterator object interface

IDeckLinkOutput

IID_IDeckLinkOutput

IDeckLinkOutput::GetDisplayModeIterator returns
an IDeckLinkDisplayModeIterator object interface

IDeckLinkEncoderInput

IID_IDeckLinkEncoderInput

IDeckLinkEncoderInput::GetDisplayModeIterator returns an
IDeckLinkDisplayModeIterator object interface

IDeckLinkDisplayMode

IID_IDeckLinkDisplayMode

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

Public Member Functions
MethodDescription

Next

Returns a pointer to an IDeckLinkDisplayMode interface foran available display mode

Section 2 — DeckLink API

79

2.5.13.1

IDeckLinkDisplayModeIterator::Next method
The Next method returns the next available IDeckLinkDisplayMode interface.
SyntaxHRESULT

Next (IDeckLinkDisplayMode *displayMode);Parameters
Name

Direction

Description

displayMode

out

IDeckLinkDisplayMode object interface or NULL when no more display
modes are available.

Return Values

2.5.14

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkDisplayMode Interface
The IDeckLinkDisplayMode object interface represents a supported display mode.
The IDeckLinkDisplayModeIterator object interface enumerates supported display modes, returning
IDeckLinkDisplayMode object interfaces.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkOuput

IID_IDeckLinkOutput

IDeckLinkOutput::GetDisplayMode returns an
IDeckLinkDisplayMode interface object

IDeckLinkInput

IID_IDeckLinkInput

IDeckLinkInput::GetDisplayMode returns an
IDeckLinkDisplayMode interface object

IDeckLinkEncoderInput

IID_IDeckLinkEncoderInput

IDeckLinkEncoderInput::GetDisplayMode returns
an IDeckLinkDisplayMode interface object

IDeckLinkDisplayMode
Iterator

IID_IDeckLinkDisplayMode
Iterator

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

Public Member Functions
MethodDescription

GetWidth

Get video frame width in pixels

GetHeight

Get video frame height in pixels

GetNameGet descriptive text

GetDisplayMode

Get corresponding BMDDisplayMode

GetFrameRate

Get the frame rate of the display mode

GetFieldDominanceGets the field dominance of the frame

GetFlags

Returns flags associated with display modes(see BMDDisplaymodeFlags for more details).

Section 2 — DeckLink API

80

2.5.14.1

IDeckLinkDisplayMode::GetWidth method
The GetWidth method returns the width of a video frame in the display mode.
Syntaxlong

GetWidth ();Return Values

2.5.14.2

Value

Description

WidthVideo frame width in pixels

IDeckLinkDisplayMode::GetHeight method
The GetHeight method returns the height of a video frame in the display mode.
Syntaxlong

GetHeight ();Return Values

2.5.14.3

Value

Description

HeightVideo frame height in pixels

IDeckLinkDisplayMode::GetName method
The GetName method returns a string describing the display mode.
SyntaxHRESULT

GetName (string *name);Parameters
Name

Direction

Description

name

out

Descriptive string. This allocated string must be freed by the callerwhen no longer required.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API81

2.5.14.4

IDeckLinkDisplayMode::GetDisplayMode method
The GetDisplayMode method returns the corresponding BMDDisplayMode for the selecteddisplay mode.
Syntax

BMDDisplayModeGetDisplayMode ();Return Values

2.5.14.5

Value

Description

mode

BMDDisplayMode corresponding to the display mode

IDeckLinkDisplayMode::GetFrameRate method
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 / frameDuration.
SyntaxHRESULT

GetFrameRate (BMDTimeValue *frameDuration, BMDTimeScale *timeScale);Parameters
Name

Direction

Description

frameDurationout

Frame duration time value

timeScaleout

Frame rate time scale

Return Values

2.5.14.6

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkDisplayMode::GetFieldDominance method
The GetFieldDominance method gets the field dominance of the frame.
SyntaxBMDFieldDominanceGetFieldDominance ();Return Values
Value

Description

FieldDominance

The field dominance see BMDFieldDominance for details.

Section 2 — DeckLink API82

2.5.14.7

IDeckLinkDisplayMode::GetFlags method
The GetFlags method returns flags associated with display modes.
Syntax

BMDDisplayModeFlags

GetFlags ();Return Values

2.5.15

Value

Description

Flags

The display mode flags see BMDDisplaymodeFlags for details.

IDeckLinkConfiguration Interface
The IDeckLinkConfiguration object interface allows querying and modification of DeckLink configuration
parameters.
An IDeckLinkConfiguration object interface can be obtained from the IDeckLink interface using
QueryInterface.
The configuration settings are globally visible (not limited to the current process). Changes will persist until
the IDeckLinkConfiguration object is released, unless WriteConfigurationToPreferences is called. In
which case, the changes will be made permanent and will persist across restarts.
Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

DeckLink device interface

Public Member Functions
MethodDescription

SetFlag

Sets a boolean value into the configuration setting associatedwith the given BMDDeckLinkConfigurationID.

GetFlag

Gets the current boolean value of a setting associated withthe given BMDDeckLinkConfigurationID.

SetInt

Sets the current int64_t value into the configuration setting
associated with the given BMDDeckLinkConfigurationID.

GetIntGets the current int64_t value of a setting associated with thegiven BMDDeckLinkConfigurationID.

SetFloat

Sets the current double value into the configuration setting
associated with the given BMDDeckLinkConfigurationID.

GetFloat

Gets the current double value of a setting associated withthe given BMDDeckLinkConfigurationID.

SetString

Sets the current string value into the configuration settingwith the given BMDDeckLinkConfigurationID.

GetStringGets the current string value of a setting associated with thegiven BMDDeckLinkConfigurationID.

WriteConfigurationToPreferences

Saves the current settings to system preferences so that they
will persist across system restarts.

Section 2 — DeckLink API83

2.5.15.1

IDeckLinkConfiguration::SetFlag method
The SetFlag method sets a boolean value into the configuration setting associated with the given
BMDDeckLinkConfigurationID.
SyntaxHRESULT

SetFlag (BMDDeckLinkConfigurationID cfgID, boolean value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The boolean value to set into the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no flag type configuration setting for this operation
corresponding to the given BMDDeckLinkConfigurationID.

E_NOTIMPL

The request is correct however it is not supported by the
DeckLink hardware.

2.5.15.2 IDeckLinkConfiguration::GetFlag method
The GetFlag method gets the current boolean value of a configuration setting associated with the given
BMDDeckLinkConfigurationID.
SyntaxHRESULT

GetFlag (BMDDeckLinkConfigurationID cfgID, boolean *value);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

out

The boolean value that is set in the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no flag type configuration setting for this operation
corresponding to the given BMDDeckLinkConfigurationID.

E_NOTIMPL

The request is correct however it is not supported by the
DeckLink hardware.

Section 2 — DeckLink API84

2.5.15.3

IDeckLinkConfiguration::SetInt method
The SetInt method sets the current int64_t value of a configuration setting associated with the given
BMDDeckLinkConfigurationID.
SyntaxHRESULT

SetInt (BMDDeckLinkConfigurationID cfgID, int64_t value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The integer value to set into the selected configuration setting.

Return Values

2.5.15.4

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no integer type configuration setting for this operation
corresponding to the given BMDDeckLinkConfigurationID.

E_NOTIMPL

The request is correct however it is not supported by the
DeckLink hardware.

IDeckLinkConfiguration::GetInt method
The GetInt method gets the current int64_t value of a configuration setting associated with the given
BMDDeckLinkConfigurationID.
SyntaxHRESULT

GetInt (BMDDeckLinkConfigurationID cfgID, int64_t *value);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

out

The integer value that is set in the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no integer type configuration setting for this operation
corresponding to the given BMDDeckLinkConfigurationID.

E_NOTIMPL

The request is correct however it is not supported by the
DeckLink hardware.

Section 2 — DeckLink API85

2.5.15.5 IDeckLinkConfiguration::SetFloat method
The SetFloat method sets the current double value of a configuration setting associated with the given
BMDDeckLinkConfigurationID.
SyntaxHRESULT

SetFloat (BMDDeckLinkConfigurationID cfgID, double value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The double value to set into the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no float type configuration setting for this operation
corresponding to the given BMDDeckLinkConfigurationID.

E_NOTIMPL

The request is correct however it is not supported by the
DeckLink hardware.

2.5.15.6 IDeckLinkConfiguration::GetFloat method
The GetFloat method gets the current double value of a configuration setting associated with the given
BMDDeckLinkConfigurationID.
SyntaxHRESULT

GetFloat (BMDDeckLinkConfigurationID cfgID, double *value);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

out

The double value that is set in the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no float type configuration setting for this operation
corresponding to the given BMDDeckLinkConfigurationID.

E_NOTIMPL

The request is correct however it is not supported by the
DeckLink hardware.

Section 2 — DeckLink API86

2.5.15.7

IDeckLinkConfiguration::SetString method
The SetString method sets the current string value of a configuration setting associated with the given
BMDDeckLinkConfigurationID.
SyntaxHRESULT

SetString (BMDDeckLinkConfigurationID cfgID, string value);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The string to set into the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no string type configuration setting for this operation
corresponding to the given BMDDeckLinkConfigurationID.

E_NOTIMPL

The request is correct however it is not supported by the
DeckLink hardware.

2.5.15.8 IDeckLinkConfiguration::GetString method
The GetString method gets the current string value of a configuration setting associated with the given
BMDDeckLinkConfigurationID.
SyntaxHRESULT

GetString (BMDDeckLinkConfigurationID cfgID, string *value);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

out

The string set in the selected configuration setting. This allocatedstring must be freed by the caller when no longer required.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no string type configuration setting for this operation
corresponding to the given BMDDeckLinkConfigurationID.

E_NOTIMPL

The request is correct however it is not supported by the
DeckLink hardware.

Section 2 — DeckLink API87

2.5.15.9 IDeckLinkConfiguration::WriteConfigurationToPreferences method
The WriteConfigurationToPreferences method saves the current settings to system preferences so they
will persist across system restarts.

NOTE This method requires administrative privileges. Configuration settings changed throughthis interface will be reverted when the interface is released unless this method is called.

SyntaxHRESULTWriteConfigurationToPreferences ();Return Values

2.5.16

Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

Insufficient privileges to write to system preferences.

IDeckLinkAPIInformation Interface
The IDeckLinkAPIInformation object interface provides global API information. A reference to an
IDeckLinkAPIInformation object interface may be obtained from CoCreateInstance on platforms withnative COM support or from CreateDeckLinkAPIInformationInstance on other platforms.
Public Member Functions
MethodDescription

GetFlag

Gets a boolean flag associated with specified BMDDeckLinkAPIInformationID

GetIntGets an int64_t associated with specified BMDDeckLinkAPIInformationID

GetFloat

Gets a float associated with specified BMDDeckLinkAPIInformationID

GetStringGets a string associated with specified BMDDeckLinkAPIInformationID

Section 2 — DeckLink API

88

2.5.16.1

IDeckLinkAPIInformation::GetFlag method
The GetFlag method gets a boolean flag associated with a given BMDDeckLinkAPIInformationID.
SyntaxHRESULT

GetFlag (BMDDeckLinkAPIInformationID cfgID, bool *value);

Parameters
Name

Direction

Description

cfgID

in

BMDDeckLinkAPIInformationID to get flag value.

value

out

Value of flag corresponding to cfgID.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no flag type attribute corresponding to cfgID.

2.5.16.2 IDeckLinkAPIInformation::GetInt method
The GetInt method gets an int64_t value associated with a given BMDDeckLinkAPIInformationID.
SyntaxHRESULT

GetInt (BMDDeckLinkAPIInformationID cfgID, int64_t *value);Parameters
Name

Direction

Description

cfgID

in

BMDDeckLinkAPIInformationID to get int value.

value

out

Value of int corresponding to cfgID.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

There is no int type attribute corresponding to cfgID.

Section 2 — DeckLink API89

2.5.16.3 IDeckLinkAPIInformation::GetFloat method
The GetFloat method gets a float value associated with a given BMDDeckLinkAPIInformationID.
SyntaxHRESULT

GetFloat (BMDDeckLinkAPIInformationID cfgID, double *value);Parameters
Name

Direction

Description

cfgID

in

BMDDeckLinkAPIInformationID to get float value.

value

out

Value of float corresponding to cfgID.

Return Values

2.5.16.4

Value

Description

S_OK

Success

E_INVALIDARG

There is no float type attribute corresponding to cfgID.

IDeckLinkAPIInformation::GetString method
The GetString method gets a string value associated with a given BMDDeckLinkAPIInformationID.
SyntaxHRESULT

GetString (BMDDeckLinkAPIInformationID cfgID, String *value);Parameters
Name

Direction

Description

cfgID

in

BMDDeckLinkAPIInformationID to get string value.

value

out

Value of string corresponding to cfgID.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

There is no string type attribute corresponding to cfgID.

E_OUTOFMEMORY

Unable to allocate memory for string

Section 2 — DeckLink API

90

2.5.17

IDeckLinkProfileAttributes Interface
The IDeckLinkProfileAttributes object interface provides details about the capabilities of a profile for 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 canbe queried using this object interface.
Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkProfileAttributes object interface may be obtained
from IDeckLink using QueryInterface

IDeckLinkProfile

IID_IDeckLinkProfile

An IDeckLinkProfileAttributes object interface may be obtained from
IDeckLinkProfile using QueryInterface.

Public Member Functions

2.5.17.1

MethodDescription

GetFlag

Gets a boolean flag corresponding to a BMDDeckLinkAttributeID

GetIntGets an int64_t corresponding to a BMDDeckLinkAttributeID

GetFloat

Gets a float corresponding to a BMDDeckLinkAttributeID

GetStringGets a string corresponding to a BMDDeckLinkAttributeID

IDeckLinkProfileAttributes::GetFlag method
The GetFlag method gets a boolean flag associated with a given BMDDeckLinkAttributeID. (See
BMDDeckLinkAttributeID for a list of attribute IDs)
SyntaxHRESULT

GetFlag (BMDDeckLinkAttributeID cfgID, boolean *value);Parameters
Name

Direction

Description

cfgID

in

BMDDeckLinkAttributeID to get flag value.

value

out

The value corresponding to cfgID.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no flag type attribute corresponding to cfgID.

Section 2 — DeckLink API91

2.5.17.2

IDeckLinkProfileAttributes::GetInt method
The GetInt method gets an int64_t value associated with a given BMDDeckLinkAttributeID.
SyntaxHRESULT

GetInt (BMDDeckLinkAttributeID cfgID, int64_t *value);Parameters
Name

Direction

Description

cfgID

in

BMDDeckLinkAttributeID to get int value.

value

out

The value corresponding to cfgID.

Return Values

2.5.17.3

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no int type attribute corresponding to cfgID.

IDeckLinkProfileAttributes::GetFloat method
The GetFloat method gets a float value associated with a given BMDDeckLinkAttributeID.
SyntaxHRESULT

GetFloat (BMDDeckLinkAttributeID cfgID, double *value);Parameters
Name

Direction

Description

cfgID

in

BMDDeckLinkAttributeID to get float value.

value

out

The value corresponding to cfgID.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no float type attribute corresponding to cfgID.

Section 2 — DeckLink API92

2.5.17.4

IDeckLinkProfileAttributes::GetString method
The GetString method gets a string value associated with a given BMDDeckLinkAttributeID.
SyntaxHRESULT

GetString (BMDDeckLinkAttributeID cfgID, string *value);Parameters
Name

Direction

Description

cfgID

in

BMDDeckLinkAttributeID to get string value.

value

out

The value corresponding to cfgID. This allocated string must be freed
by the caller when no longer required.

Return Values

2.5.18Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no string type attribute corresponding to cfgID.

IDeckLinkMemoryAllocator Interface
The IDeckLinkMemoryAllocator object interface is a callback class used to provide control over the
memory intensive video frame allocations required during playback and capture. An object with
the IDeckLinkMemoryAllocator object interface may be registered as a callback with the
IDeckLinkOutput or IDeckLinkInput interfaces.
During playback or capture, calls will be made to this interface object to manage memory buffers forstoring video frame data. Memory buffers may be allocated and released more frequently than once pervideo frame played back or captured, such as when video format conversion is performed.

TIP Implementation of this interface is optional if this callback is not registered, a default allocator will be used.

Related Interfaces
Interface

Interface ID

Description

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkMemoryAllocator object interface may be registered with
IDeckLinkOutput::SetVideoOutputFrameMemoryAllocator

IDeckLinkInput

IID_IDeckLinkInput

An IDeckLinkMemoryAllocator object interface may be registered with
IDeckLinkInput::SetVideoInputFrameMemoryAllocator

Public Member Functions
MethodDescription

AllocateBuffer

Called to allocate memory for a frame

ReleaseBuffer

Called to release a previously allocated frameCommitCalled to notify the allocator that frame buffers will be required

Decommit

Called to notify the allocator that frame buffers will no longer be required(until next call to Commit).

Section 2 — DeckLink API93

2.5.18.1

IDeckLinkMemoryAllocator::AllocateBuffer method
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.
SyntaxHRESULT

AllocateBuffer (unsigned long bufferSize, void *allocatedBuffer);Parameters
Name

Direction

Description

bufferSize

inSize of the memory to be allocated for a new video frame

allocatedBuffer

outAddress of newly allocated buffer
NOTE: Returned address for buffer must be aligned on a 16-byteboundary.

Return Values
Value

Description

S_OK

Success

E_OUTOFMEMORY

There is insufficient memory to allocate a buffer of the requested size.

2.5.18.2 IDeckLinkMemoryAllocator::ReleaseBuffer method
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.
SyntaxHRESULT

ReleaseBuffer (void *buffer);Parameters
Name

Direction

Description

bufferin

Pointer to the buffer to be released

Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API

94

2.5.18.3 IDeckLinkMemoryAllocator::Commit method
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.
SyntaxHRESULT

Commit ();Parameters
none.
Return Values

2.5.18.4

Value

Description

S_OK

Success

E_OUTOFMEMORY

There is insufficient memory to allocate a buffer of the requested size.

IDeckLinkMemoryAllocator::Decommit method
The Decommit method is called by the owner interface to notify the allocator that frame buffers will nolonger 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 theapplication developer.
SyntaxHRESULTDecommit ();Parameters
none.
Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API95

2.5.19

IDeckLinkKeyer Interface
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

Interface ID

Description

IDeckLink

IID_IDeckLink

DeckLink device interface

Public Member Functions

2.5.19.1

MethodDescription

EnableTurn on keyer.

SetLevel

Set the level that the image is blended into the frame.

RampUp

Progressively blends in an image over a given number of frames

RampDown

Progressively blends out an image over a given number of frames

DisableTurn off keyer

IDeckLinkKeyer::Enable method
The Enable method turns on 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. Currently capture of mask/key on dual channel
inputs is not supported.
The following table displays hardware which supports the keyer functionality.
DeviceInternal

ExternalSD

HD to p30

HD to p60

UHD to p30

UHD to p60

DeckLink Duo

yes

no

yes

no

—

—

—

DeckLink Quad

yes

no

yes

no

—

—

—

DeckLink SDI 4K

yes

no

yes

yes

yes

no

—

DeckLink Studio 4K

yes

yes*

yes

yes

yes

no

—

DeckLink 4K Extreme

yes

yes

yes

yes

yes

no

—

DeckLink 4K Extreme 12G

yes

yes

yes

yes

yes

yes

yes

DeckLink 4K Pro

yes

yes

yes

yes

yes

yes

yes

DeckLink Duo 2

yes

yes

yes

yes

yes

—

—

DeckLink Quad 2

yes

yes

yes

yes

yes

—

—

DeckLink 8K Pro

yes

yes

yes

yes

yes

yes

yes

DeckLink IP/SDI HD

yes***

no

yes

yes

yes

—

—

DeckLink IP HD

yes

no

yes

yes

yes

—

—

DeckLink IP HD Optical

yes

no

yes

yes

yes

—

—

UltraStudio 4K

yes

yes

yes

yes

yes

no

—

UltraStudio 4K Extreme

yes

yes

yes

yes

yes

yes

yes**

UltraStudio 4K Extreme 3

yes

yes

yes

yes

yes

yes

yes

Section 2 — DeckLink API

96

Device

Internal

ExternalSD

HD to p30

HD to p60

UHD to p30

UHD to p60

UltraStudio 4K Mini

yes

yes

yes

yes

yes

yes

no

UltraStudio HD Mini

yes

yes

yes

yes

yes

—

—

= Video mode not supported for playback* = SD Only** = Over PCIe only*** = Ethernet input only

TIP The IDeckLinkOutput::DoesSupportVideoMode method with video mode flag
bmdSupportedVideoModeKeying should be used to determine whether keying is supported
on a device with a particular display mode.

SyntaxHRESULT

Enable (boolean isExternal);Parameters
Name

Direction

Description

isExternalinSpecifies internal or external keying.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.19.2 IDeckLinkKeyer::SetLevel method
The SetLevel method sets the level that the image is blended onto the frame. 0 is no blend, 255 iscompletely blended onto the frame.
SyntaxHRESULT

SetLevel (uint8_t level);Parameters
Name

Direction

Description

level

in

The level that the image is to be blended onto the frame.

Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API97

2.5.19.3

IDeckLinkKeyer::RampUp method
The RampUp method progressively blends in an image over a given number of frames from 0 to 255.
SyntaxHRESULT

RampUp (uint32_t numberOfFrames);Parameters
Name

Direction

Description

numberOfFramesin

The number of frames that the image is progressively blended in.

Return Values

2.5.19.4

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkKeyer::RampDown method
The RampDown method progressively blends out an image over a given number of frames from 255 to 0.
SyntaxHRESULT

RampDown (uint32_t numberOfFrames);Parameters
Name

Direction

Description

numberOfFramesin

The number of frames that the image is progressively blended out.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.19.5 IDeckLinkKeyer::Disable method
The Disable method turns off the keyer functionality.
SyntaxHRESULTDisable();Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

98

2.5.20

IDeckLinkVideoFrameAncillary Interface
The IDeckLinkVideoFrameAncillary object interface represents the ancillary data associated with a video
frame. CEA-708 closed-captions are encoded with data bits in the 2 least-signficant-bits of each 10 bit
pixel component. These bits are not preserved when capturing in an 8 bit pixel format. To capture or
output CEA-708 captions, a 10 bit pixel format such as bmdFormat10BitYUV must be used.

NOTE The IDeckLinkVideoFrameAncillary object interface is for existing designs or where theancillary data does not conform to SMPTE 291M type 2 ANC packet format. For new designs with
VANC packets, the use of IDeckLinkVideoFrameAncillaryPackets object interface is preferred.

Related Interfaces
Interface

Interface ID

Description

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkVideoFrameAncillary object can be obtainedwith IDeckLinkOutput::CreateAncillaryData.

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

An IDeckLinkVideoFrameAncillary object can be obtained
from IDeckLinkVideoFrame::GetAncillaryData.

IDeckLinkMutableVideoFrame

IID_
IDeckLinkMutableVideoFrame

An IDeckLinkVideoFrameAncillaryobject be set into a video frame using
IDeckLinkMutableVideoFrame::SetAncillaryData.

Public Member Functions
MethodDescription

GetPixelFormat

Gets pixel format of a video frame.

GetDisplayMode

Gets corresponding BMDDisplayMode for the selecteddisplay mode.

GetBufferForVerticalBlankingLine

Access vertical blanking line buffer.

2.5.20.1 IDeckLinkVideoFrameAncillary::GetPixelFormat method
The GetPixelFormat method gets the pixel format of a video frame.
Syntax

BMDPixelFormat

GetPixelFormat ();Return Values
Value

Description

PixelFormat

Pixel format of video frame (BMDPixelFormat)

Section 2 — DeckLink API99

2.5.20.2 IDeckLinkVideoFrameAncillary::GetDisplayMode method
The GetDisplayMode method returns the corresponding BMDDisplayMode for the selecteddisplay mode.
Syntax

BMDDisplayModeGetDisplayMode ();Return Values
Value

Description

mode

BMDDisplayMode corresponding to the display mode.

2.5.20.3 IDeckLinkVideoFrameAncillary::GetBufferForVerticalBlankingLine method
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 fromfour, 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.
SyntaxHRESULT

GetBufferForVerticalBlankingLine (uint32_t lineNumber, void* *buffer)Parameters
Name

Direction

Description

lineNumberinAncillary line number to access.

bufferout

Pointer into ancillary buffer for requested line or NULL if line number
was invalid.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

An invalid ancillary line number was requested

Section 2 — DeckLink API100

2.5.21

IDeckLinkVideoFrameAncillaryPackets Interface
The IDeckLinkVideoFrameAncillaryPackets object interface represents the collection of ancillary data
packets associated with a video frame. It is the preferred interface for the capture and output of SMPTE
291M Type 2 VANC packets, replacing legacy IDeckLinkVideoFrameAncillary interface.
An IDeckLinkVideoFrameAncillaryPackets interface may be obtained from an IDeckLinkVideoFrame
object interface using QueryInterface.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

An IDeckLinkVideoFrameAncillaryPacket object interface
may be obtained from IDeckLinkVideoFrame using
QueryInterface

IDeckLinkAncillary

IID_

PacketIterator

IDeckLinkAncillaryPacketIterator

IDeckLinkAncillaryPacket

IID_IDeckLinkAncillaryPacket

IDeckLinkVideoFrameAncillaryPackets::GetPacketIterator
returns an IDeckLinkAncillaryPacketIterator object interface
IDeckLinkVideoFrameAncillaryPackets::GetFirstPacketByID
returns an IDeckLinkAncillaryPacket object interface

Public Member Functions

2.5.21.1

MethodDescription

GetPacketIterator

Get a iterator that enumerates the available ancillary packets

GetFirstPacketByID

Get the first ancillary packet matching a given DID/SDID pair

AttachPacket

Add an ancillary packet to the video frame

DetachPacket

Remove an ancillary packet from the video frame

DetachAllPackets

Remove all ancillary packets from the video frame.

IDeckLinkVideoFrameAncillaryPackets::GetPacketIterator method
The GetPacketIterator method returns an iterator that enumerates the available ancillary packets for avideo frame.
SyntaxHRESULT

GetPacketIterator (IDeckLinkAncillaryPacketIterator *iterator);Parameters
Name

Direction

Description

iteratorout

Pointer to ancillary packet iterator. This object must be released by thecaller when no longer required.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

Parameter iterator variable is NULL

E_OUTOFMEMORY

Unable to create iterator

Section 2 — DeckLink API101

2.5.21.2 IDeckLinkVideoFrameAncillaryPackets::GetFirstPacketByID method
The GetFirstPacketByID method returns the first ancillary packet in the video frame
matching a given DID/SDID pair.
SyntaxHRESULTetFirstPacketByID (uint8_t DID, uint8_t SDID,
G
IDeckLinkAncillaryPacket *packet);Parameters
Name

Direction

Description

DID

in

Data ID (DID)

SDID

in

Secondary Data ID (SDID)

packetout

Pointer to ancillary packet. This object must be released by the callerwhen no longer required.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

Parameter packet variable is NULL

2.5.21.3 IDeckLinkVideoFrameAncillaryPackets::AttachPacket method
The AttachPacket method adds an ancillary packet to the video frame.
SyntaxHRESULTAttachPacket (IDeckLinkAncillaryPacket *packet);Parameters
Name

Direction

Description

packetinAncillary packet to attach

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

Parameter packet variable is NULL or has invalid data stream index

E_OUTOFMEMORY

Unable to allocate memory for packet

Section 2 — DeckLink API102

2.5.21.4 IDeckLinkVideoFrameAncillaryPackets::DetachPacket method
The DetachPacket method removes an ancillary packet from the video frame.
SyntaxHRESULT

DetachPacket (IDeckLinkAncillaryPacket *packet)
Parameters
Name

Direction

Description

packetinAncillary packet to detach

Return Values
Value

Description

S_FALSE

Packet not found

S_OK

Success

2.5.21.5 IDeckLinkVideoFrameAncillaryPackets::DetachAllPackets method
The DetachAllPackets method removes all ancillary packets from the video frame.
SyntaxHRESULTDetachAllPackets ();Return Values

2.5.22

Value

Description

S_OK

Success

IDeckLinkAncillaryPacketIterator Interface
The IDeckLinkAncillaryPacketIterator object interface is used to enumerate the available ancillary
packets in a video frame.
A reference to an IDeckLinkAncillaryPacketIterator object interface for an input
video frame may be obtained by calling GetPacketIterator on a IDeckLinkVideoFrameAncillaryPackets
object interface.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrame
AncillaryPackets

IID_IDeckLinkVideoFrame
AncillaryPackets

IDeckLinkVideoFrameAncillaryPackets::GetPacketIterator returns an IDeckLinkAncillaryPacketIterator
object interface

IDeckLinkAncillaryPacket

IID_IDeckLinkAncillaryPacket

IDeckLinkAncillaryPacketIterator::Next
returns IDeckLinkAncillaryPacket interfaces representing eachancillary packet in a video frame

Public Member Functions
MethodDescription

Next

Returns an IDeckLinkAncillaryPacket object interface
corresponding to an individual ancillary packet.

Section 2 — DeckLink API103

2.5.22.1

IDeckLinkAncillaryPacketIterator::Next method
The Next method creates an object representing an ancillary data packet and assigns the address of the
IDeckLinkAncillaryPacket interface of the newly created object to the packet parameter.
SyntaxHRESULT

Next (IDeckLinkAncillaryPacket *packet);Parameters
Name

Direction

Description

packetout

Pointer to IDeckLinkAncillaryPacket interface object or NULL when no
more ancillary packets are available. This object must be released by
the caller when no longer required.

Return Values

2.5.23

Value

Description

S_FALSENo (more) packets found

S_OK

Success

E_INVALIDARG

Parameter packet variable is NULL

IDeckLinkAncillaryPacket Interface
The IDeckLinkAncillaryPacket object interface represents an ancillary data packet within a Video Frame.
A reference to an IDeckLinkAncillaryPacket object interface can either be obtained with a known DID/
SDID by calling GetFirstPacketByID on a IDeckLinkVideoFrameAncillaryPackets or via the
IDeckLinkAncillaryPacketIterator interface.

TIP Developers may subclass IDeckLinkAncillaryPacket to implement a specific VANC data packet type.

Related Interfaces
Interface

Interface ID

Description

IDeckLinkAncillary
PacketIterator

IID_IDeckLinkAncillary
PacketIterator

IDeckLinkAncillaryPacketIterator::Next
returns IDeckLinkAncillaryPacket interfaces representing
each ancillary packet in a video frame

IDeckLinkVideoFrame
AncillaryPackets

IID_IDeckLinkVideoFrame
AncillaryPackets

IDeckLinkVideoFrameAncillaryPackets::GetFirstPacketByID
returns an IDeckLinkAncillaryPacket object interface

Public Member Functions
MethodDescription

GetBytes

Get pointer to ancillary packet data

GetDID

Get Data ID (DID) for ancillary packet

GetSDID

Get Secondary Data ID (SDID) for ancillary packet

GetLineNumber

Get the video frame line number of ancillary packet

GetDataStreamIndex

Get the data stream index for ancillary packet

Section 2 — DeckLink API104

2.5.23.1

IDeckLinkAncillaryPacket::GetBytes method
The GetBytes method allows direct access to the data buffer of the ancillary packet.

TIP When subclassing IDeckLinkAncillaryPacket, implement GetBytes with support of at least one type of
BMDAncillaryPacketFormat. Specify NULL for either output parameter if unwanted.

SyntaxHRESULT

GetBytes (BMDAncillaryPacketFormat format, const void *data, uint32_t *size);

Parameters
Name

Direction

Description

formatin

Requested format of data buffer output (BMDAncillaryPacketFormat)

data

out

Pointer to ancillary packet data buffer. The pointer is valid while
IDeckLinkAncillaryPacket object remains valid.

out

Number of elements in the data buffer. When the requested format
is bmdAncillaryPacketFormatYCbCr10, this value will be the size inpixels. For other ancillary packet formats, it will be the length of thebuffer in units of the format’s type size.

size

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_NOTIMPL

Format not implemented

2.5.23.2 IDeckLinkAncillaryPacket::GetDID method
The GetDID method returns the Data ID (DID) of the ancillary packet.
Syntax

uint8̲t

GetDID ();Return Values
Value

Description

DID

Data ID (DID) of the ancillary packet

2.5.23.3 IDeckLinkAncillaryPacket::GetSDID method
The GetSDID method returns the SecondaryData ID (SDID) of the ancillary packet.
Syntax

uint8_t

GetSDID ();Return Values
Value

Description

SDID

Secondary Data ID (SDID) of the ancillary packet

Section 2 — DeckLink API

105

2.5.23.4 IDeckLinkAncillaryPacket::GetLineNumber method
The GetLineNumber method returns the video frame line number of an ancillary packet. When subclassing
IDeckLinkAncillaryPacket for VANC output, if GetLineNumber returns 0, the ancillary packet will be assigned aline automatically determined by the driver.
Syntax

uint32_t

GetLineNumber ();Return Values
Value

Description

LineNumber

Video frame line number of the ancillary packet

2.5.23.5 IDeckLinkAncillaryPacket::GetDataStreamIndex method
The GetDataStreamIndex method returns a data stream index of the ancillary packet.
This function should only return 0 for SD modes. In HD and above, this function will normally return 0 to
output the ancillary packet in luma color channel. However this function can return 1 to encode a second
data stream in the chroma color channel, but this should only occur when the first data stream iscompletely full.
Syntax

uint8_t

GetDataStreamIndex ();Return Values

2.5.24

Value

Description

DataStreamIndex

Data stream index for the ancillary packet

IDeckLinkTimecode Interface
The IDeckLinkTimecode object interface represents a video timecode and provides methods to accessthe timecode or its components.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

IDeckLinkVideoFrame::GetTimecode returns
an IDeckLinkTimecode object interface

Public Member Functions
MethodDescription

GetBCD

Get timecode in BCD

GetComponents

Get timecode components

GetStringGet timecode as formatted string

GetFlags

Get timecode flags

GetTimecodeUserBits

Get timecode user bits.

Section 2 — DeckLink API

106

2.5.24.1

IDeckLinkTimecode::GetBCD method
The GetBCD method returns the timecode in Binary Coded Decimal representation.
SyntaxBMDTimecodeBCD

GetBCD();

Return Values
Value

Description

Timecode

Timecode value in BCD format (See BMDTimecodeBCD for details)

2.5.24.2 IDeckLinkTimecode::GetComponents method
The GetComponents method returns individual components of the timecode. Specify NULL for any
unwanted parameters.
SyntaxHRESULT

etComponents (uint8_t *hours, uint8_t *minutes,
G
uint8_t *seconds, uint8_t *frames);

Parameters
Name

Direction

Description

hours

out

Hours component of timecode

minutesout

Minutes component of timecode

seconds

out

Seconds component of timecode

framesout

Frames component of timecode

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API107

2.5.24.3 IDeckLinkTimecode::GetString method
The GetString method returns the timecode formatted as a standard timecode string.
SyntaxHRESULT

GetString (string *timecode);Parameters
Name

Direction

Description

timecodeoutTimecode formatted as a standard timecode string: “HH:MM:SS:FF”.
This allocated string must be freed by the caller when nolonger required

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.24.4 IDeckLinkTimecode::GetFlags method
The GetFlags method returns the flags accompanying a timecode.
SyntaxBMDTimecodeFlags GetFlags()
Return Values
Value

Description

TimecodeFlags

Timecode flags (see BMDTimecodeFlags for details)

2.5.24.5 IDeckLinkTimecode::GetTimecodeUserBits method
The GetTimecodeUserBits method returns the timecode user bits.
SyntaxHRESULT

GetTimecodeUserBits (BMDTimecodeUserBits *userBits);

Parameters
Name

Direction

Description

userBitsout

The user bits.

Return Values
Value

Description

E_POINTER

The userBits parameter is NULL.

S_OK

Success

Section 2 — DeckLink API108

2.5.25

IDeckLinkScreenPreviewCallback Interface
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.

TIP 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

Interface ID

Description

IDeckLinkInput

IID_IDeckLinkInput

An IDeckLinkScreenPreviewCallback object interface may be registered with
IDeckLinkInput::SetScreenPreviewCallback

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkScreenPreviewCallback object interface may be registered with
IDeckLinkOutput::SetScreenPreviewCallback

Public Member Functions
MethodDescription

DrawFrame

Called when a new frame is available for the preview display

2.5.25.1 IDeckLinkScreenPreviewCallback::DrawFrame method
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 callback’s
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 hasn’t changed since the last time the callback wascalled, the frame parameter will be NULL.

SyntaxHRESULTDrawFrame(IDeckLinkVideoFrame *theFrame);

Parameters
Name

Direction

Description

theFrameinVideo frame to preview

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API109

2.5.26

IDeckLinkGLScreenPreviewHelper Interface
The IDeckLinkGLScreenPreviewHelper object interface may be used with a simple
IDeckLinkScreenPreviewCallback implementation to provide OpenGL based preview rendering which isdecoupled from the incoming or outgoing video stream being previewed.
A reference to an IDeckLinkGLScreenPreviewHelper interface may be obtained from CoCreateInstanceon platforms with native COM support or from CreateOpenGLScreenPreviewHelper (OpenGL 2.0) or
CreateOpenGL3ScreenPreviewHelper (OpenGL 3.2) 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(-1.0, 1.0, -1.0, 1.0, -1.0, 1.0);
glMatrixMode(GL_MODELVIEW);— Create an IDeckLinkGLScreenPreviewHelper object interface using CoCreateInstance orCreateOpenGLScreenPreviewHelper
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
IDeckLinkGLScreenPreviewHelper::SetFrame from
IDeckLinkScreenPreviewCallback::DrawFrame— R egister an instance of the IDeckLinkScreenPreviewCallback subclass with
IDeckLinkInput::SetScreenPreviewCallback or
IDeckLinkOutput::SetScreenPreviewCallback as appropriate.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkScreenPreview

IID_IDeckLinkScreenPreview

IDeckLinkGLScreenPreviewHelper::SetFrame may be calledfrom IDeckLinkScreenPreview::DrawFrame

Public Member Functions
MethodDescription

InitializeGL

Initialize GL previewing

PaintGL

Repaint the GL preview

SetFrame

Set the preview frame to display on the next PaintGL call

Set3DPreviewFormat

Set the 3D preview format.

Section 2 — DeckLink API

110

2.5.26.1 IDeckLinkGLScreenPreviewHelper::InitializeGL method
The InitializeGL method should be called from the preview OpenGL context during initialization ofthat context.
SyntaxHRESULTInitializeGL();

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.26.2 IDeckLinkGLScreenPreviewHelper::PaintGL method
The PaintGL method should be called from the preview OpenGL context whenever the preview frame
needs to be repainted. Frames to be displayed should be provided to
IDeckLinkGLScreenPreviewHelper::SetFrame.
PaintGL and SetFrame allow OpenGL updates to be decoupled from new frame availability.
SyntaxHRESULTPaintGL();

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.26.3 IDeckLinkGLScreenPreviewHelper::SetFrame method
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 not be displayed or
may be displayed multiple times.
SyntaxHRESULTSetFrame(IDeckLinkVideoFrame *theFrame)

Parameters
Name

Direction

Description

theFrameinVideo frame to preview

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

111

2.5.26.4 IDeckLinkGLScreenPreviewHelper::Set3DPreviewFormat
The Set3DPreviewFormat method is used to set the 3D preview format.
SyntaxHRESULTSet3DPreviewFormat(BMD3DPreviewFormat *previewFormat);

Parameters
Name

Direction

Description

previewFormat

in

The 3D preview format. See the Linked frame preview format(BMD3DPreviewFormat) section for more details.

Return Values

2.5.27

Value

Description

S_OK

Success

IDeckLinkCocoaScreenPreviewCallback Interface
The IDeckLinkCocoaScreenPreviewCallback object interface is a cocoa callback class which is called tofacilitate 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.

TIP 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

Interface ID

Description

IDeckLinkInput

IID_IDeckLinkInput

An IDeckLinkCocoaScreenPreviewCallback
object interface may be registered with
IDeckLinkInput::SetScreenPreviewCallback

IDeckLinkOutput

IID_IDeckLinkOutput

An IDeckLinkCocoaScreenPreviewCallback
object interface may be registered with
IDeckLinkOutput::SetScreenPreviewCallback

Section 2 — DeckLink API112

2.5.28

IDeckLinkDX9ScreenPreviewHelper Interface
The IDeckLinkDX9ScreenPreviewHelper object interface may be used with a simple
IDeckLinkScreenPreviewCallback implementation to provide DirectX based preview rendering which isdecoupled from the incoming or outgoing video stream being previewed.
A reference to an IDeckLinkDX9ScreenPreviewHelper object is obtained from CoCreateInstance.
Typical usage of IDeckLinkDX9ScreenPreviewHelper is as follows:— Create an IDeckLinkDX9ScreenPreviewHelper object interface using CoCreateInstance.
— If 3D preview is required, call IDeckLinkDX9ScreenPreviewHelper::Set3DPreviewFormat— Setup Direct 3D parameters:
D3DPRESENT_PARAMETERS

d3dpp;

IDirect3DDevice9*			dxDevice;
d3dpp.BackBufferFormat = D3DFMT_UNKNOWN;
d3dpp.BackBufferCount = 2;d3dpp.Windowed = TRUE;
d3dpp.SwapEffect = D3DSWAPEFFECT_DISCARD;
d3dpp.hDeviceWindow = hwnd;
d3dpp.PresentationInterval = D3DPRESENT_INTERVAL_DEFAULT;— Create a new device:
CreateDevice(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hwnd, D3DCREATE_HARDWARE_
VERTEXPROCESSING | D3DCREATE_MULTITHREADED, &d3dpp, &dxDevice);— Call IDeckLinkDX9ScreenPreviewHelper::Initialize (dxDevice)
When repainting, call the following methods:
dxDevice->BeginScene();— IDeckLinkDX9ScreenPreviewHelper::Render();dxDevice->EndScene();— Create a subclass of IDeckLinkScreenPreviewCallback which calls
IDeckLinkDX9ScreenPreviewHelper::SetFrame from IDeckLinkScreenPreviewCallback::DrawFrame.
— Register an instance of the IDeckLinkScreenPreviewCallback subclass with
IDeckLinkInput::SetScreenPreviewCallback or IDeckLinkOutput::SetScreenPreviewCallback
as appropriate.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkScreenPreview

IID_IDeckLinkScreenPreview

IDeckLinkDX9ScreenPreviewHelper::SetFrame may becalled from IDeckLinkScreenPreview::DrawFrame

Public Member Functions
MethodDescription

Initialize

Initialize DirectX previewing.

RenderRepaint the DirectX preview.

SetFrame

Set the preview frame for display.

Set3DPreviewFormat

Set the 3D preview format.

Section 2 — DeckLink API113

2.5.28.1 IDeckLinkDX9ScreenPreviewHelper::Initialize method
The Initialize method sets the IDirect3DDevice9 object to be used by the DeckLink API’s preview helper.
SyntaxHRESULT

Initialize (void *device);Parameters
Name

Direction

Description

devicein

The IDirect3DDevice9 object

Return Values
Value

Description

S_OK

Success

2.5.28.2 IDeckLinkDX9ScreenPreviewHelper::Render method
The Render method should be called whenever the preview frame needs to be repainted. The frames tobe displayed should be provided to IDeckLinkDX9ScreenPreviewHelper::SetFrame.
SyntaxHRESULTRender (RECT *rc)Parameters
Name

Direction

Descriptionrcin

The display surface rectangle. If rc is NULL, the whole view port /surface is used. If the rc dimensions have changed, the display texture
will be resized.

Return Values
Value

Description

S_OK

Success

2.5.28.3 IDeckLinkDX9ScreenPreviewHelper::SetFrame method
The SetFrame method will set a 2D or 3D IDeckLinkVideoFrame into a texture. This method is used to set the preview
frame to display on the next call to IDeckLinkDX9ScreenPreviewHelper::Render. Depending on the rate and timing ofcalls to SetFrame and Render, some frames may not be displayed or may be displayed multiple times.
SyntaxHRESULT

SetFrame (IDeckLinkVideoFrame *primaryFrame);Parameters
Name

Direction

Description

primaryFramein

The video frame to preview.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API114

2.5.28.4 IDeckLinkDX9ScreenPreviewHelper::Set3DPreviewFormat method
The Set3DPreviewFormat method is used to set the 3D preview format.
SyntaxHRESULT

Set3DPreviewFormat (BMD3DPreviewFormat previewFormat);Parameters
Name

Direction

Description

previewFormat

in

The 3D preview format. See the ‘Frame preview format’ section(BMD3DPreviewFormat) for more details.

Return Values

2.5.29Value

Description

S_OK

Success

IDeckLinkDeckControl Interface
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

Interface ID

Description

IDeckLinkDeckControl

IID_IDeckLinkDeckControl

An IDecklinkDeckControl object interface may beobtained from IDeckLink using QueryInterface.

IDeckLinkDeckControlStatus
Callback

IID_IDeckLinkDeck
ControlStatusCallback

An IDeckLinkDeckControlStatusCallback
object interface may be registered with
IDeckLinkDeckControl::SetCallback.

Public Member Functions
MethodDescription

Open

Open a connection to the deck.

Close

Close the connection to the deck.

GetCurrentState

Get the current state of the deck.

SetStandby

Put the deck into standby mode.

SendCommand

Send a custom command to the deck.

Play

Send a play command to the deck.

Stop

Send a stop command to the deck.

TogglePlayStop

Toggle between play and stop mode.

Eject

Send an eject command to the deck.

GoToTimecode

Set the deck to go the specified timecode on the tape.

FastForward

Send a fast forward command to the deck.

RewindSend a rewind command to the deck.

Section 2 — DeckLink API

115

Public Member Functions
MethodDescription

StepForward

Send a step forward command to the deck.

StepBack

Send a step back command to the deck.

Jog

Send a jog forward / reverse command to the deck.

ShuttleSend a shuttle forward / reverse command to the deck.

GetTimecodeString

Get a timecode from deck in string format.

GetTimecode

Get a timecode from deck in IDeckLinkTimeCode format.

GetTimecodeBCD

Get a timecode from deck in BMDTimecodeBCD format.

SetPreroll

Set the preroll period.

GetPreroll

Get the preroll period.

SetCaptureOffset

Set the field accurate capture timecode offset.

GetCaptureOffset

Current capture timecode offset

SetExportOffset

Set the field accurate export timecode offset.

GetExportOffset

Get the current setting of the field accurate export timecode offset.

GetManualExportOffset

Get the recommended delay fields of the current deck.

StartExport

Start an export to tape.

StartCapture

Start a capture.

GetDeviceID

Get deck device ID.

Abort

Stop current deck operation.

CrashRecordStart

Send a record command to the deck.

CrashRecordStop

Send a stop record command to the deck.

SetCallback

Set a deck control status callback.

Section 2 — DeckLink API116

2.5.29.1 IDeckLinkDeckControl::Open method
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.
The application should wait for a IDeckLinkDeckControlStatusCallback::DeckControlStatusChanged
callback notification with the bmdDeckControlStatusDeckConnected bit set before using the rest of thedeck control functionality.
SyntaxHRESULTpen (BMDTimeScale timeScale, BMDTimeValue timeValue,Oboolean timecodeIsDropFrame, BMDDeckControlError *error)

Parameters
Name

Direction

Description

timeScalein

The time scale.

timeValuein

The time value in units of BMDTimeScale.

timecodeIsDropFramein

Timecode is drop frame (TRUE) or a non drop frame (FALSE).

error

out

The error code from the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

2.5.29.2 IDeckLinkDeckControl::Close method
The Close method will optionally place the deck in standby mode before closing the connection.
SyntaxHRESULT

Close (boolean standbyOn)Parameters
Name

Direction

Description

standbyOn

inPlace the deck into standby mode (TRUE) before disconnection.

Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API117

2.5.29.3 IDeckLinkDeckControl::GetCurrentState method
The GetCurrentState method will get the current state of the deck.
SyntaxHRESULT

etCurrentState (BMDDeckControlMode *mode, BMDDeckControlVTRControlState
G*vtrControlState, BMDDeckControlStatusFlags *flags);

Parameters
Name

Direction

Description

mode

out

The deck control mode see BMDDeckControlMode for details.

vtrControlStateout

The deck control state see BMDDeckControlVTRControlStatefor details.

flags

out

The deck control status flags see BMDDeckControlStatusFlags
for details.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

2.5.29.4 IDeckLinkDeckControl::SetStandby method
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.
SyntaxHRESULT

SetStandby (boolean standbyOn);
Parameters
Name

Direction

Description

standbyOnin

Set standby on (TRUE) , or set standby off (FALSE)

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API118

2.5.29.5 IDeckLinkDeckControl::SendCommand method
The SendCommand method will send a custom command to the deck. A custom command operation
cannot occur if there is an export-to-tape, capture or a custom command operation in progress. The
supplied custom command must conform to the Sony 9 Pin protocol and must not include the checksum
byte. It will be generated by this interface and added to the command. The deck’s response (minus thechecksum) is stored in the provided buffer.
SyntaxHRESULT

endCommand (uint8_t *inBuffer, uint32_t inBufferSize, uint8_t *outBuffer,S
uint32_t *outDataSize, uint32_t outBufferSize, BMDDeckControlError *error);

Parameters
Name

Direction

Description

inBufferin

The buffer containing the command packet to transmit.

inBufferSize

in

The size of the buffer containing the command packet to transmit.

outBufferout

The buffer to contain the response packet.

outDataSizeout

The size of the response data.

outBufferSize

out

The size of the buffer that will contain the response packet.

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_INVALIDARG

One or more parameters are invalid.

E_UNEXPECTED

A previous custom command is still being processed.

E_FAIL

Failure check error parameter

S_OK

Success

2.5.29.6 IDeckLinkDeckControl::Play method
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.
SyntaxHRESULT

Play (BMDDeckControlError *error);

Parameters
Name

Direction

Description

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

Section 2 — DeckLink API

119

2.5.29.7 IDeckLinkDeckControl::Stop method
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.
SyntaxHRESULT

Stop (BMDDeckControlError *error);

Parameters
Name

Direction

Description

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

2.5.29.8 IDeckLinkDeckControl::TogglePlayStop method
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.
SyntaxHRESULT

TogglePlayStop (BMDDeckControlError *error);

Parameters
Name

Direction

Description

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

Section 2 — DeckLink API120

2.5.29.9 IDeckLinkDeckControl::Eject method
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.
SyntaxHRESULT

Eject (BMDDeckControlError *error);

Parameters
Name

Direction

Description

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

2.5.29.10 IDeckLinkDeckControl::GoToTimecode method
The GoToTimecode method will send a “go to timecode” command to the deck.
SyntaxHRESULT

GoToTimecode (BMDTimecodeBCD timecode, BMDDeckControlError *error);

Parameters
Name

Direction

Description

timecodein

The timecode to go to.

error

out

The error code sent by the deck -see BMDDeckControlErrorfor details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

Section 2 — DeckLink API121

2.5.29.11 IDeckLinkDeckControl::FastForward method
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.
SyntaxHRESULT

FastForward (boolean viewTape, BMDDeckControlError *error);

Parameters
Name

Direction

Description

viewTapeinView the tape (TRUE) or enable automatic selection of “tape view” or“end to end view” (FALSE)

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

2.5.29.12 IDeckLinkDeckControl::Rewind method
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.
SyntaxHRESULT

Rewind (boolean viewTape, BMDDeckControlError *error);

Parameters
Name

Direction

Description

viewTapeinView the tape (TRUE) or enable automatic selection of “tape view” or“end to end view” (FALSE)

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

One or more parameters are invalid.

Section 2 — DeckLink API122

2.5.29.13 IDeckLinkDeckControl::StepForward method
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.
SyntaxHRESULT

StepForward (BMDDeckControlError *error);

Parameters
Name

Direction

Description

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

2.5.29.14 IDeckLinkDeckControl::StepBack method
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.
SyntaxHRESULT

StepBack (BMDDeckControlError *error);

Parameters
Name

Direction

Description

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

Section 2 — DeckLink API1232.5.29.15 IDeckLinkDeckControl::Jog method
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.
SyntaxHRESULTJog (double rate, BMDDeckControlError *error);

Parameters
Name

Direction

Description

rate

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

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

2.5.29.16 IDeckLinkDeckControl::Shuttle method
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.
SyntaxHRESULT

Shuttle (double rate, BMDDeckControlError *error);

Parameters
Name

Direction

Description

rate

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

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

Section 2 — DeckLink API124

2.5.29.17 IDeckLinkDeckControl::GetTimecodeString method
The GetTimecodeString method will return the current timecode in string format.
SyntaxHRESULT

GetTimecodeString (string currentTimeCode, BMDDeckControlError *error);

Parameters
Name

Direction

Description

currentTimeCodeout

The current timecode in string format.

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

2.5.29.18 IDeckLinkDeckControl::GetTimecode method
The GetTimecode method will return the current timecode in IDeckLinkTimecode format.
SyntaxHRESULT

GetTimecode (IDeckLinkTimecode currentTimecode, BMDDeckControlError *error);

Parameters
Name

Direction

Description

currentTimeCodeout

The current timecode in IDeckLinkTimecode format.

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

2.5.29.19 IDeckLinkDeckControl::GetTimecodeBCD method
The GetTimecodeBCD method will return the current timecode in BCD format.
SyntaxHRESULT

GetTimecodeBCD (BMDTimecodeBCD *currentTimecode, BMDDeckControlError *error);

Parameters
Name

Direction

Description

currentTimeCodeout

The timecode in BCD format.

error

out

The error code sent by the deck see BMDDeckControlError for details.

Section 2 — DeckLink API

125

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

2.5.29.20 IDeckLinkDeckControl::SetPreroll method
The SetPreroll method will set the preroll time period.
SyntaxHRESULT

SetPreroll (uint32_t prerollSeconds);Parameters
Name

Direction

Description

prerollSecondsin

The preroll period in seconds to set.

Return Values
Value

Description

S_OK

Success

2.5.29.21 IDeckLinkDeckControl::GetPreroll method
The GetPreroll method will get the preroll period setting.
SyntaxHRESULT

GetPreroll (uint32_t *prerollSeconds);Parameters
Name

Direction

Description

prerollSeconds

out

The current preroll period.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

The parameter is invalid.

Section 2 — DeckLink API

126

2.5.29.22 IDeckLinkDeckControl::SetCaptureOffset method
The capture offset may be used to compensate for a deck specific offset between the inpoint and the timeat which the capture starts.
SyntaxHRESULT

SetCaptureOffset (int32_t captureOffsetFields);
Parameters
Name

Direction

Description

captureOffsetFields

in

The timecode offset to set in fields.

Return Values
Value

Description

S_OK

Success

2.5.29.23 IDeckLinkDeckControl::GetCaptureOffset method
The GetCaptureOffset method will return the current setting of the field accurate capture timecode offset in fields.
SyntaxHRESULT

GetCaptureOffset (int32_t *captureOffsetFields);
Parameters
Name

Direction

Description

captureOffsetFields

out

The current timecode offset in fields.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

The parameter is invalid.

2.5.29.24 IDeckLinkDeckControl::SetExportOffset method
The SetExportOffset method will set the current export timecode offset in fields. This method permits finecontrol of the timecode offset to tailor for the response of an individual deck by adjusting the number offields prior to the in or out point where an export will begin or end.
SyntaxHRESULT

SetExportOffset (int32_t exportOffsetFields);
Parameters
Name

Direction

Description

exportOffsetFields

in

The timecode offset in fields.

Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API

127

2.5.29.25 IDeckLinkDeckControl::GetExportOffset method
The GetExportOffset method will return the current setting of the export offset in fields.
SyntaxHRESULT

GetExportOffset (int32_t * exportOffsetFields);
Parameters
Name

Direction

Description

exportOffsetFields

out

The current timecode offset in fields.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

The parameter is invalid.

2.5.29.26 IDeckLinkDeckControl::GetManualExportOffset method
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.
SyntaxHRESULT

GetManualExportOffset (int32_t * deckManualExportOffsetFields);
Parameters
Name

Direction

Description

deckManualExportOffsetFields

out

The current timecode offset.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

The parameter is invalid.

Section 2 — DeckLink API

128

2.5.29.27 IDeckLinkDeckControl::StartExport method
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
IDeckLinkDeckControlStatusCallback::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 IDeckLinkDeckControl::SetPreroll and an offset
period set using IDeckLinkDeckControl::SetExportOffset.
After StartExport is called, the export will commence when the current time code 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 bmdDeckControlExportCompleteEventin the IDeckLinkDeckControlStatusCallback::DeckControlEventReceived will occur several frames from the“outTimecode”.
Resources may be released at this point or another export may be commenced.
SyntaxHRESULTtartExport (BMDTimecodeBCD inTimecode, BMDTimecodeBCD outTimecode,
S
BMDDeckControlExportModeOpsFlags exportModeOps, BMDDeckControlError *error);

Parameters
Name

Direction

Description

inTimecodein

The timecode to start the export sequence.

outTimecodein

The timecode to stop the export sequence.

exportModeOps

in

The export mode operations see
BMDDeckControlExportModeOpsFlags for details.

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

Section 2 — DeckLink API

129

2.5.29.28 IDeckLinkDeckControl::StartCapture method
The StartCapture method starts a capture operation using the given parameters. Prior to calling this method, theinput 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 isreceived via IDeckLinkDeckControlStatusCallback::DeckControlEventReceived callback. Reception of that event
signals that the serial timecodes attached to the IDeckLinkVideoFrame objects (received via
IDeckLinkInputCallback::VideoInputFrameArrived) can be used to determine if the frame is between theinTimecode 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
IDeckLinkDeckControlStatus Callback::DeckControlEventReceived method will occur several frames from the“outTimecode”. Resources may be released at this point. IDeckLinkDeckControl will return to VTR control mode.
SyntaxHRESULTtartCapture (boolean useVITC, BMDTimecodeBCD inTimecode,S
BMDTimecodeBCD outTimecode, BMDDeckControlError *error);

Parameters
Name

Direction

Description

useVITCin

If true use VITC as the source of timecodes.

inTimecodein

The timecode to start the capture sequence.

outTimecodein

The timecode to stop the capture sequence.

error

out

Error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

Section 2 — DeckLink API

130

2.5.29.29 IDeckLinkDeckControl::GetDeviceID method
The GetDeviceID method gets the device ID returned by the deck.
The IDeckLinkDeckControl must be in VTR control mode for this command to succeed.
SyntaxHRESULT

GetDeviceID (uint16_t *deviceId, BMDDeckControlError *error);

Parameters
Name

Direction

Description

deviceIdout

The code for the device model.

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

2.5.29.30 IDeckLinkDeckControl::Abort method
The Abort operation is synchronous. Completion is signaled with a bmdDeckControlAbortedEvent event.
SyntaxHRESULTA bort (void);

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.29.31 IDeckLinkDeckControl::CrashRecordStart method
The CrashRecordStart method sets the deck to record. The IDeckLinkDeckControl object must be in
VTR control mode for this command to succeed.
SyntaxHRESULT

CrashRecordStart (BMDDeckControlError *error);

Parameters
Name

Direction

Description

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

Section 2 — DeckLink API131

2.5.29.32 IDeckLinkDeckControl::CrashRecordStop method
The CrashRecordStop method stops the deck record operation.
The IDeckLinkDeckControl object must be in VTR control mode for this command to succeed.
SyntaxHRESULT

CrashRecordStop (BMDDeckControlError *error);

Parameters
Name

Direction

Description

error

out

The error code sent by the deck see BMDDeckControlError for details.

Return Values
Value

Description

E_FAIL

Failure check error parameter.

S_OK

Success

E_INVALIDARG

The parameter is invalid.

2.5.29.33 IDeckLinkDeckControl::SetCallback method
The SetCallback method installs a callback object to be called when deck control events occur.
SyntaxHRESULT

SetCallback (IDeckLinkDeckControlStatusCallback *callback);Parameters
Name

Direction

Description

callbackin

The callback object implementing the
IDeckLinkDeckControlStatusCallback object interface

Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API132

2.5.30

IDeckLinkDeckControlStatusCallback Interface
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 callbackwith the IDeckLinkDeckControl interface.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkDeckControl

IID_IDeckLinkDeckControl

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

Public Member Functions
MethodDescription

TimecodeUpdate

Called when there is a change to the timecode.

VTRControlStateChanged

Called when the control state of the deck changes.

DeckControlEventReceived

Called when a deck control event occurs.

DeckControlStatusChanged

Called when deck control status has changed.

2.5.30.1 IDeckLinkDeckControlStatusCallback::TimecodeUpdate method
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.
SyntaxHRESULT

TimecodeUpdate (BMDTimecodeBCD currentTimecode);Parameters
Name

Direction

Description

currentTimecodein

The current timecode.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

133

2.5.30.2 IDeckLinkDeckControlStatusCallback::VTRControlStateChanged method
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.
SyntaxHRESULT

VTRControlStateChanged(BMDDeckControlVTRControlState newState, BMDDeckControlError error);

Parameters
Name

Direction

Description

newStatein

The new deck control state see BMDDeckControlVTRControlStatefor details.

error

in

The deck control error code.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.30.3 IDeckLinkDeckControlStatusCallback::DeckControlEventReceived method
The DeckControlEventReceived method is called when a deck control event occurs.
SyntaxHRESULT eckControlEventReceived
D(BMDDeckControlEvent event, BMDDeckControlError error);

Parameters
Name

Direction

Description

event

in

The deck control event that has occurred see BMDDeckControlEventfor details.

error

in

The deck control error that has occurred.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API134

2.5.30.4 IDeckLinkDeckControlStatusCallback::DeckControlStatusChanged method
The DeckControlStatusChanged method is called when the deck control status has changed.
SyntaxHRESULT

DeckControlStatusChanged (BMDDeckControlStatusFlags flags, uint32_t mask);Parameters
Name

Direction

Description

flags

in

The deck control current status see BMDDeckControlStatusFlags
for details.

mask

in

The deck control status event flag(s) that has changed.

Return Values

2.5.31

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkDiscovery Interface
The IDeckLinkDiscovery object interface is used to install or remove the callback for receiving DeckLink
device discovery notifications. A reference to an IDeckLinkDiscovery object interface may be obtained
from CoCreateInstance on platforms with native COM support or from CreateDeckLinkDiscoveryInstanceon other platforms.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkDevice
NotificationCallback

IID_IDeckLinkDevice
NotificationCallback

A device notification callback can be installed with
IDeckLinkDiscovery::InstallDeviceNotifications or uninstalledwith IDeckLinkDiscovery::UninstallDeviceNotifications

Public Member Functions
MethodDescription

InstallDeviceNotifications

Install DeckLink device notifications callback

UninstallDeviceNotifications

Remove DeckLink device notifications callback

Section 2 — DeckLink API

135

2.5.31.1

IDeckLinkDiscovery::InstallDeviceNotifications method
The InstallDeviceNotifications method installs the IDeckLinkDeviceNotificationCallback callback which
will be called when a new DeckLink device becomes available.
SyntaxHRESULT nstallDeviceNotifications
I(IDeckLinkDeviceNotificationCallback* deviceCallback);Parameters
Name

Direction

Description

deviceCallbackinCallback object implementing the
IDeckLinkDeviceNotificationCallback object interface.

Return Values
Value

Description

E_INVALIDARG

The parameter variable is NULL

E_FAIL

FailureS_OK

Success

2.5.31.2 IDeckLinkDiscovery:: UninstallDeviceNotifications method
The UninstallDeviceNotifications method removes the DeckLink device notifications callback. When thismethod returns, it guarantees there are no ongoing callbacks to the
IDeckLinkDeviceNotificationCallback instance.
SyntaxHRESULTUninstallDeviceNotifications (void);

Return Values

2.5.32

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkDeviceNotificationCallback
The IDeckLinkDeviceNotificationCallback object interface is callback which is called when a DeckLink
device arrives or is removed.
Public Member Functions
MethodDescription

DeckLinkDeviceArrived

A DeckLink device has arrived.

DeckLinkDeviceRemoved

A DeckLink device has been removed.

Section 2 — DeckLink API

136

2.5.32.1

IDeckLinkDeviceNotificationCallback::DeckLinkDeviceArrived method
The DeckLinkDeviceArrived method is called when a new DeckLink device becomes available.
This method will be called on an API private thread.
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.
SyntaxHRESULT

DeckLinkDeviceArrived (IDeckLink* deckLinkDevice);Parameters
NamedeckLinkDevice

Direction

Descriptionin

DeckLink device. The IDeckLink reference will be released when the
callback returns. To hold on to it beyond the callback, call AddRef.
Your application then owns the IDeckLink reference and is responsible
for managing the IDeckLink object’s lifetime. The reference can bereleased at any time (including in the DeckLinkDeviceRemoved
callback) by calling Release.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.32.2 IDeckLinkDeviceNotificationCallback::DeckLinkDeviceRemoved method
The DeckLinkDeviceRemoved method is called when a DeckLink device is disconnected. This method
will be called on an API private thread.
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.
SyntaxHRESULT

DeckLinkDeviceRemoved (IDeckLink* deckLinkDevice);Parameters
Name

Direction

Description

deckLinkDevice

in

DeckLink device.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

137

2.5.33

IDeckLinkNotification Interface
The IDeckLinkNotification object interface is used to install or remove the callback for receiving DeckLink
device notifications.
An IDeckLinkNotification object interface may be obtained from IDeckLink
using QueryInterface.
Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkNotification object interface may beobtained from IDeckLink using QueryInterface

IDeckLinkNotificationCallback

IID_IDeckLinkNotification
Callback

An IDeckLinkNotificationCallback object can be
subscribed using IDeckLinkNotification::Subscribe or
unsubscribed using IDeckLinkNotification::Unsubscribe

Public Member Functions

2.5.33.1

MethodDescription

Subscribe

Subscribe a notification. Please see BMDNotifications
for more details.

Unsubscribe

Unsubscribe a notification

IDeckLinkNotification::Subscribe method
The Subscribe method registers a callback object for a given topic.
SyntaxHRESULTubscribe (BMDNotifications topic,
S
IDeckLinkNotificationCallback *theCallback);Parameters
Name

Direction

Description

topic

in

The notification event type.

theCallbackin

The callback object implementing the IDeckLinkNotificationCallback
object interface.

Return Values
Value

Description

E_INVALIDARG

The callback parameter variable is NULL

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API138

2.5.33.2 IDeckLinkNotification::Unsubscribe method
The Unsubscribe method removes a notification event type from a callback object.
SyntaxHRESULTnsubscribe (BMDNotifications topic, IDeckLinkNotificationCallback
U*theCallback);Parameters
Name

Direction

Description

topic

in

The notification event type.

theCallbackin

The callback object implementing the
IDeckLinkNotificationCallback object interface.

Return Values

2.5.34

Value

Description

E_INVALIDARG

The callback parameter variable is NULL

E_FAIL

FailureS_OK

Success

IDeckLinkNotificationCallback Interface
The IDeckLinkNotificationCallback object interface is used to notify the application about a subscribed event.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkNotification

An IDeckLinkNotificationCallback object can be subscribed using
IID_ IDeckLinkNotification IDeckLinkNotification::Subscribe An IDeckLinkNotificationCallback
object can be unsubscribed using IDeckLinkNotification::Unsubscribe

Public Member Functions
MethodDescription

NotifyCalled when a subscribed notification event has occurred.

Section 2 — DeckLink API139

2.5.34.1

IDeckLinkNotificationCallback::Notify method
The Notify method is called when subscribed notification occurs.
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.
SyntaxHRESULT

Notify(BMDNotifications topic, uint64_t param1, uint64_t param2);Parameters
Name

Direction

Description

topic

in

The type of notification. Please see BMDNotifications for more details.

param1in

The first parameter of the notification.

param2in

The second parameter of the notification.

Return Values

2.5.35

Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkEncoderInput Interface
The IDeckLinkEncoderInput object interface allows an application to capture an encoded video andaudio stream from a DeckLink device.
An IDeckLinkEncoderInput interface can be obtained from an IDeckLink object interface using
QueryInterface. If QueryInterface for an input interface is called on a device which does not support
encoded capture, then QueryInterface will fail and return E_NOINTERFACE.
Encoded Video capture operates in a push model with encoded video data delivered to
an IDeckLinkEncoderInputCallback object interface. Audio capture is optional and can be handled byusing the same callback object.
Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkEncoderInput object interface may be obtained
from IDeckLink using QueryInterface

IDeckLinkDisplay
ModeIterator

IID_IDeckLinkDisplay
ModeIterator

IDeckLinkEncoderInput::GetDisplayModeIterator returns an
IDeckLinkDisplayModeIterator object interface

IDeckLinkEncoder
InputCallback

IID_IDeckLinkEncoder
InputCallback

An IDeckLinkEncoderInputCallback object interface may beregistered with IDeckLinkEncoderInput::SetCallback

IDeckLinkDisplayMode

IID_IDeckLinkDisplayMode

IDeckLinkEncoderInput::GetDisplayMode returns
an IDeckLinkDisplayMode interface object

Public Member Functions
MethodDescription

DoesSupportVideoMode

Check whether a given video mode is supported for input

GetDisplayModeGet a display mode object based on identifier

Section 2 — DeckLink API

140

Public Member Functions

2.5.35.1

MethodDescription

GetDisplayModeIterator

Get an iterator to enumerate the available input display modes

EnableVideoInput

Configure video input

DisableVideoInput

Disable video input

GetAvailablePacketsCount

Query number of available encoded packets

SetMemoryAllocator

Register custom memory allocator for encoded video packets

EnableAudioInput

Configure audio input

DisableAudioInput

Disable audio input

GetAvailableAudioSampleFrameCount

Query audio buffer status

StartStreams

Start encoded capture

StopStreams

Stop encoded capture

PauseStreams

Pause encoded capture

FlushStreams

Removes any buffered video and audio frames.

SetCallback

Register input callback

GetHardwareReferenceClockGet the hardware system clock

IDeckLinkEncoderInput::DoesSupportVideoMode method
The DoesSupportVideoMode method indicates whether a given display mode is supported on encoder input.
SyntaxHRESULTDoesSupportVideoMode(BMDVideoConnection connection, BMDDisplayMode requestedMode,
BMDPixelFormat requestedCodec, uint32_t requestedCodecProfile,
BMDSupportedVideoModeFlags flags, bool *supported);Parameters
Name

Direction

Description

connection

in

Input connection to check (see BMDVideoConnection for details).

requestedModein

Display mode to check.

requestedCodec

in

Encoded pixel format to check.

requestedCodecProfile

in

Codec profile to check.

flags

in

Input video mode flags(see BMDSupportedVideoModeFlags for details).

supportedout

Returns true if the display mode is supported.

Return Values
Value

Description

E_INVALIDARG

Either parameter requestedMode has an invalid value or parameter
supported variable is NULL.

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

141

2.5.35.2 IDeckLinkEncoderInput::GetDisplayMode method
The GetDisplayMode method returns the IDeckLinkDisplayMode object interface for an input display
mode identifier.
SyntaxHRESULT

etDisplayMode (BMDDisplayMode displayMode,G
IDeckLinkDisplayMode *resultDisplayMode);

Parameters
Name

Direction

Description

displayModein

The display mode ID (See BMDDisplayMode).

resultDisplayMode

out

Pointer to the display mode with matching ID. The object must be
released by the caller when no longer required.

Return Values
Value

Description

E_INVALIDARG

Either parameter displayMode has an invalid value or parameter
resultDisplayMode variable is NULL.

E_OUTOFMEMORY

Insufficient memory to create the result display mode object.

S_OK

Success

2.5.35.3 IDeckLinkEncoderInput::GetDisplayModeIterator
The GetDisplayModeIterator method returns an iterator which enumerates the available display modes.
SyntaxHRESULT

GetDisplayModeIterator (IDeckLinkDisplayModeIterator *iterator);

Parameters
Name

Direction

Description

iteratorout

display mode iterator

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API142

2.5.35.4 IDeckLinkEncoderInput::EnableVideoInput
The EnableVideoInput method configures video input and puts the hardware into encoded video capturemode. Video input (and optionally audio input) is started by calling StartStreams.
SyntaxHRESULTnableVideoInput (BMDDisplayMode displayMode,
E
BMDPixelFormat pixelFormat, BMDVideoInputFlags flags);

Parameters
Name

Direction

Description

displayModeinVideo mode to capture

pixelFormat

in

Encoded pixel format to capture

flags

in

Capture flags

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

Is returned on invalid mode or video flags

E_ACCESSDENIED

Unable to access the hardware or input stream currently active

E_OUTOFMEMORY

Unable to create a new frame

2.5.35.5 IDeckLinkEncoderInput::DisableVideoInput
The DisableVideoInput method disables the hardware video capture mode.
SyntaxHRESULTDisableVideoInput ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API143

2.5.35.6 IDeckLinkEncoderInput::EnableAudioInput
The EnableAudioInput method configures audio input and puts the hardware into audio capture mode.
Encoded audio and video input is started by calling StartStreams.
SyntaxHRESULTnableAudioInput (BMDAudioFormat audioFormat, BMDAudioSampleRate sampleRate,
E
BMDAudioSampleType sampleType, uint32_t channelCount);

Parameters
Name

Direction

Description

audioFormat

in

Audio format to encode.

sampleRatein

Sample rate to capture

sampleTypein

Sample type to capturechannelCountin

Number of audio channels to capture – only 2, 8 or 16 channel capture
is supported.

Return Values
Value

Description

E_FAIL

FailureE_INVALIDARG

Invalid audio format or number of channels requested

E_ACCESSDENIED

Unable to access the hardware or input stream currently active

S_OK

Success

2.5.35.7 IDeckLinkEncoderInput::DisableAudioInput
The DisableAudioInput method disables the hardware audio capture mode.
SyntaxHRESULTDisableAudioInput ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

144

2.5.35.8 IDeckLinkEncoderInput::StartStreams
The StartStreams method starts encoded video and audio capture as configured with EnableVideoInput
and optionally EnableAudioInput.
SyntaxHRESULT

StartStreams ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

Input stream is already running.

E_UNEXPECTED

Video and Audio inputs are not enabled.

2.5.35.9 IDeckLinkEncoderInput::StopStreams
The StopStreams method stops encoded video and audio capture.
SyntaxHRESULTStopStreams ();Parameters
none.
Return Values
Value

Description

E_ACCESSDENIED

Input stream already stopped.

S_OK

Success

2.5.35.10 IDeckLinkEncoderInput::PauseStreams
The PauseStreams method pauses encoded video and audio capture. Capture time continues while thestreams are paused but no video or audio will be captured. Paused capture may be resumed bycalling PauseStreams again. Capture may also be resumed by calling StartStreams but capture time
will be reset.
SyntaxHRESULTPauseStreams ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API145

2.5.35.11 IDeckLinkEncoderInput::FlushStreams
The FlushStreams method removes any buffered video packets and audio frames.
SyntaxHRESULTFlushStreams ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.35.12 IDeckLinkEncoderInput::SetCallback
The SetCallback method configures a callback which will be called as new encoded video, and audio
packets become available. Encoder capture is started with StartStreams, stopped with StopStreams andmay be paused with PauseStreams.
SyntaxHRESULTSetCallback (IDeckLinkEncoderInputCallback *theCallback);Parameters
Name

Direction

Description

theCallbackinCallback object implementing the IDeckLinkEncoderInputCallback
object interface

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API146

2.5.35.13 IDeckLinkEncoderInput::GetHardwareReferenceClock
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 isenabled (see IDeckLinkEncoderInput::EnableVideoInput for details).
SyntaxHRESULT

etHardwareReferenceClock (BMDTimeScale desiredTimeScale, BMDTimeValueG*hardwareTime, BMDTimeValue *timeInFrame, BMDTimeValue *ticksPerFrame);

Parameters
Name

Direction

Description

desiredTimeScalein

Desired time scale

hardwareTime

out

Hardware reference time (in units of desiredTimeScale)timeInFrame

out

Time in frame (in units of desiredTimeScale)ticksPerFrame

out

Number of ticks for a frame (in units of desiredTimeScale)

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.35.14 IDeckLinkEncoderInput::SetMemoryAllocator
The SetMemoryAllocator method sets a custom memory allocator for encoded video packet allocations
during capture. Use of a custom memory allocator is optional.
SyntaxHRESULT

SetMemoryAllocator (IDeckLinkMemoryAllocator *theAllocator);Parameters
Name

Direction

Description

theAllocatorin

Allocator object with an IDeckLinkMemoryAllocator interface

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API147

2.5.35.15 IDeckLinkEncoderInput::GetAvailableAudioSampleFrameCountThe 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 madeavailable via IDeckLinkEncoderInputCallback and may be ignored.
SyntaxHRESULT

GetAvailableAudioSampleFrameCount (uint32_t *availableSampleFrameCount);Parameters
Name

Direction

Description

availableSampleFrameCountout

The number of buffered audio frames currently available.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.35.16 IDeckLinkEncoderInput::GetAvailablePacketsCount method
The GetAvailablePacketsCount method provides the number of encoded video packets that are queued
to be delivered to the IDeckLinkEncoderInputCallback::VideoPacketArrived callback.
SyntaxHRESULT

GetAvailablePacketsCount(uint32_t* availablePacketsCount)

Parameters
Name

Direction

Description

availablePacketsCountout

Number of available encoded packets

Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API148

2.5.36

IDeckLinkEncoderInputCallback Interface
The IDeckLinkEncoderInputCallback object interface is a callback class which is called to provide
encoded video packets and audio data during an encoded capture operation.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkEncoder
Input

IID_IDeckLinkEncoder
Input

An IDeckLinkEncoderInputCallback object interface may beregistered with IDeckLinkEncoderInput::SetCallback

IDeckLinkEncoder
VideoPacket

IID_IDeckLinkEncoder
VideoPacket

An IDeckLinkEncoderVideoPacket object interface is passed
to IDeckLinkEncoderInputCallback::VideoPacketArrived

IDeckLinkEncoder
AudioPacket

IID_IDeckLinkEncoder
AudioPacket

An IDeckLinkEncoderAudioPacket object interface is passed
to IDeckLinkEncoderInputCallback::AudioPacketArrived

Public Member Functions
MethodDescription

VideoInputSignalChanged

Called when a video input signal change is detectedVideoPacketArrived

Called when new video data is available

AudioPacketArrived

Called when new audio data is available

2.5.36.1 IDeckLinkEncoderInputCallback::VideoInputSignalChanged method
The VideoInputSignalChanged method is called when a video signal change has been detected by
the hardware.
To enable this feature, the bmdVideoInputEnableFormatDetection flag must be set whencalling IDeckLinkEncoderInput::EnableVideoInput().
SyntaxHRESULTideoInputSignalChanged (BMDVideoInputFormatChangedEvents notificationEvents,
V
IDeckLinkDisplayMode *newDisplayMode,
BMDDetectedVideoInputFormatFlags detectedSignalFlags);

Parameters
Name

Direction

Description

notificationEventsinThe notification events

newDisplayModein

The new display mode.

detectedSignalFlags

in

The detected signal flags.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API149

2.5.36.2 IDeckLinkEncoderInputCallback::VideoPacketArrived
The VideoPacketArrived method is called when an encoded packet has arrived. The 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.
When encoded capture is started using bmdFormatH265, this callback is used to deliver VCL and
non-VCL NAL units.
SyntaxHRESULTVideoPacketArrived (IDeckLinkEncoderVideoPacket* videoPacket);Parameters
Name

videoPacket

Direction

Descriptionin

The encoded packet that has arrived. The packet is only valid forthe duration of the callback. To hold on to the packet beyond thecallback call AddRef, and to release the packet when it is no longer
required call Release.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.36.3 IDeckLinkEncoderInputCallback::AudioPacketArrived
The AudioPacketArrived method is called when audio capture is enabled with
IDeckLinkEncoderInput::EnableAudioInput, and an audio packet has arrived. The 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.
SyntaxHRESULT

AudioPacketArrived (IDeckLinkEncoderAudioPacket* audioPacket);Parameters
Name

audioPacket

Direction

Descriptionin

The audio packet that has arrived. The audio packet is only valid forthe duration of the callback. To hold on to the audio packet beyond
the callback call AddRef, and to release the audio packet when it is nolonger required call Release.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API150

2.5.37

IDeckLinkEncoderPacket Interface
The IDeckLinkEncoderPacket object interface represents an encoded data packet.
The GetSize method may be used to determine the size of the encoded packet.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkEncoderVideoPacket

IID_IDeckLinkEncoder
VideoPacket

IDeckLinkEncoderVideoPacket subclasses
IDeckLinkEncoderPacket

IDeckLinkEncoderAudioPacket

IID_IDeckLinkEncoder
AudioPacket

IDeckLinkEncoderAudioPacket subclasses
IDeckLinkEncoderPacket

Public Member Functions

2.5.37.1

MethodDescription

GetBytes

Get pointer to encoded packet data

GetSizeGet size of encoded packet data

GetStreamTime

Get video packet timing information

GetPacketType

Get video packet type

IDeckLinkEncoderPacket::GetBytes method
The GetBytes method allows direct access to the data buffer of an encoded packet.
SyntaxHRESULT

GetBytes (void *buffer);Parameters
Name

Direction

Description

bufferout

Pointer to raw encoded buffer – only valid while object remains valid.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.37.2 IDeckLinkEncoderPacket::GetSize method
The GetSize method returns the number of bytes in the encoded packet.
Syntaxlong GetSize ();Return Values
Value

Description

BytesCount

Number of bytes in the encoded packet buffer

Section 2 — DeckLink API151

2.5.37.3 IDeckLinkEncoderPacket::GetStreamTime method
The GetStreamTime method returns the time of an encoded video packet for a given timescale.
SyntaxHRESULT

GetStreamTime (BMDTimeValue *frameTime, BMDTimeScale timeScale);Parameters
Name

Direction

Description

frameTimeout

Frame time (in units of timeScale)timeScaleinTime scale for output parameters

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.37.4 IDeckLinkEncoderPacket::GetPacketType method
The GetPacketType method returns the packet type of the encoded packet.
Syntax

BMDPacketType

GetPacketType ();Return Values

2.5.38Value

Description

PacketType

Packet type of encoded packet (BMDPacketType)

IDeckLinkEncoderVideoPacket Interface
The IDeckLinkEncoderVideoPacket object interface represents an encoded video packet which has
been captured by an IDeckLinkEncoderInput object interface. IDeckLinkEncoderVideoPacket is a
subclass of IDeckLinkEncoderPacket and inherits all its methods.
The data in the encoded packet is encoded according to the pixel format returned by GetPixelFormat –see BMDPixelFormat for details.
Objects with an IDeckLinkEncoderPacket interface are passed to the
IDeckLinkEncoderInputCallback::VideoPacketArrived callback.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkEncoderInput

IID_IDeckLinkEncoderInput

Encoded input packets are passed to
IDeckLinkEncoderInputCallback::VideoPacketArrived
by the IDeckLinkEncoderInput interface

IDeckLinkEncoderPacket

IID_IDeckLink
EncoderPacket

IDeckLinkEncoderVideoPacket subclasses
IDeckLinkEncoderPacket

IDeckLinkH265NALPacket

IID_IDeckLink
H265NALPacket

IDeckLinkH265NALPacket is available from
IDeckLinkEncoderVideoPacket via QueryInterface

Section 2 — DeckLink API

152

Public Member Functions
MethodDescription

GetPixelFormat

Get pixel format for video packet

GetHardwareReferenceTimestamp

Get hardware reference timestamp

GetTimecode

Gets timecode information

2.5.38.1 IDeckLinkEncoderVideoPacket::GetPixelFormat method
The GetPixelFormat method returns the pixel format of the encoded packet.
Syntax

BMDPixelFormat

GetPixelFormat ();Return Values
Value

Description

PixelFormat

Pixel format of encoded packet(BMDPixelFormat)

2.5.38.2 IDeckLinkEncoderVideoPacket::GetHardwareReferenceTimestamp method
The GetHardwareReferenceTimestamp method returns frame time and frame duration for agiven timescale.
SyntaxHRESULT

etHardwareReferenceTimestamp (BMDTimeScale timeScale,G
BMDTimeValue *frameTime, BMDTimeValue *frameDuration);

Parameters
Name

Direction

Description

timeScalein

The time scale see BMDTimeScale for details.

frameTimeout

The frame time see BMDTimeValue for details.

frameDurationout

The frame duration see BMDTimeValue for details.

Return Values
Value

Description

E_INVALIDARG

Timescale is not set

S_OK

Success

Section 2 — DeckLink API

153

2.5.38.3 IDeckLinkEncoderVideoPacket::GetTimecode method
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.
SyntaxHRESULT

GetTimecode (BMDTimecodeFormat format, IDeckLinkTimecode *timecode);Parameters
Name

Direction

Description

formatin

BMDTimecodeFormat to query

timecodeout

New IDeckLinkTimecode object interface containing the requested
timecode or NULL if requested timecode is not available.

Return Values

2.5.39Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

An invalid or unsupported timecode format was requested.

S_FALSEThe requested timecode format was not present or valid in
the ancillary data.

IDeckLinkEncoderAudioPacket Interface
The IDeckLinkEncoderAudioPacket object interface represents an encoded audio packet which has
been captured by an IDeckLinkEncoderInput object interface. IDeckLinkEncoderAudioPacket is a
subclass of IDeckLinkEncoderPacket and inherits all its methods.

NOTE The data in the encoded packet is encoded according to the audio format returned by
GetAudioFormat (see BMDAudioFormat for details).
Objects with an IDeckLinkEncoderAudioPacket interface are passed to the
IDeckLinkEncoderInputCallback::VideoEncoderAudioPacketArrived callback.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkEncoderInput

IID_IDeckLink
EncoderInput

Encoded audio packets are passed
to IDeckLinkEncoderInputCallback::AudioPacketArrived
by the IDeckLinkEncoderInput interface

IDeckLinkEncoderPacket

IID_IDeckLink
EncoderPacket

IDeckLinkEncoderAudioPacket subclasses
IDeckLinkEncoderPacket

Public Member Functions
MethodDescription

GetAudioFormat

Get audio format for packet

Section 2 — DeckLink API154

2.5.39.1

IDeckLinkEncoderAudioPacket::GetAudioFormat method
The GetAudioFormat method returns the audio format of the encoded packet
SyntaxBMDAudioFormat

GetAudioFormat ();Return Values

2.5.40Value

Description

AudioFormat

Audio format of encoded packet (BMDAudioFormat)

IDeckLinkH265NALPacket Interface
The IDeckLinkH265NALPacket object interface represents a H.265 encoded packet which has been
captured by an IDeckLinkEncoderVideoPacket object interface. An IDeckLinkH265NALPacket instancecan be obtained from IDeckLinkEncoderVideoPacket via QueryInterface when the captured pixel format
is bmdFormatH265, otherwise QueryInterface will fail and return E_NOINTERFACE.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkEncoderVideoPacket

IID_IDeckLinkEncoder
VideoPacket

IDeckLinkH265NALPacket is available from
IDeckLinkEncoderVideoPacket via QueryInterface

Public Member Functions

2.5.40.1

MethodDescription

GetUnitType

The H.265 NAL unit type

GetBytesNoPrefix

The H.265 encoded buffer without the NAL start code prefix.

GetSizeNoPrefix

The size of the encoded buffer without the NAL start code prefix.

IDeckLinkH265NALPacket::GetUnitType method
The GetUnitType method returns the H.265 NAL packet unit type.
SyntaxHRESULT

GetUnitType (uint8_t *unitType);Parameters
Name

Direction

Description

unitTypeout

H.265 NAL unit type

Return Values
Value

Description

E_INVALIDARG

If unitType is not provided

S_OK

Success

Section 2 — DeckLink API

155

2.5.40.2 IDeckLinkH265NALPacket::GetBytesNoPrefix method
The GetBytesNoPrefix method allows direct access to the data buffer of an encoded packet without the
NAL start code prefix.
SyntaxHRESULT

GetBytesNoPrefix (void *buffer);Parameters
Name

Direction

Description

bufferout

Pointer to raw encoded buffer without start code prefix – only valid
while object remains valid.

Return Values
Value

Description

S_OK

Success

2.5.40.3 IDeckLinkH265NALPacket::GetSizeNoPrefix method
The GetSizeNoPrefix method returns the number of bytes in the encoded packet without the NAL startcode prefix.
Syntaxlong

GetSizeNoPrefix ();Return Values

2.5.41

Value

Description

BytesCount

Number of bytes in the encoded packet buffer without the start code prefix

IDeckLinkEncoderConfiguration Interface
The IDeckLinkEncoderConfiguration object interface allows querying and modification of DeckLink
encoder configuration parameters.
An IDeckLinkEncoderConfiguration object interface can be obtained from the
IDeckLinkEncoderInput interface using QueryInterface.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkEncoderInput

IID_IDeckLinkEncoderInput

DeckLink encoder input interface

Public Member Functions
MethodDescription

SetFlag

Sets a boolean value into the configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.

GetFlag

Gets the current boolean value of a setting associated with the given
BMDDeckLinkEncoderConfigurationID.

SetInt

Sets the current int64_t value into the configuration setting associated with thegiven BMDDeckLinkEncoderConfigurationID.

GetIntGets the current int64_t value of a setting associated with the given
BMDDeckLinkEncoderConfigurationID.

SetFloat

Sets the current double value into the configuration setting associated with thegiven BMDDeckLinkEncoderConfigurationID.

Section 2 — DeckLink API

156

Public Member Functions

2.5.41.1

MethodDescription

GetFloat

Gets the current double value of a setting associated with the given
BMDDeckLinkEncoderConfigurationID.

SetString

Sets the current string value into the configuration setting with the given
BMDDeckLinkEncoderConfigurationID.

GetStringGets the current string value of a setting associated with the given
BMDDeckLinkEncoderConfigurationID.

GetBytes

Gets the current byte array value of a setting associated with the given
BMDDeckLinkEncoderConfigurationID.

IDeckLinkEncoderConfiguration::SetFlag method
The SetFlag method sets a boolean value into the configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.
SyntaxHRESULT

SetFlag (BMDDeckLinkEncoderConfigurationID cfgID, bool *value);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The boolean value to set into the selected configuration setting.

Return Values

2.5.41.2

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no flag type configuration setting for this operation
corresponding to the given BMDDeckLinkEncoderConfigurationID.

IDeckLinkEncoderConfiguration::GetFlag method
The GetFlag method gets the current boolean value of a configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.
SyntaxHRESULT

GetFlag (BMDDeckLinkEncoderConfigurationID cfgID, bool *value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

out

The boolean value that is set in the selected configuration setting.

Section 2 — DeckLink API

157

Return Values

2.5.41.3

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no flag type configuration setting for this operation
corresponding to the given BMDDeckLinkEncoderConfigurationID.

IDeckLinkEncoderConfiguration::SetInt method
The SetInt method sets the current int64_t value of a configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.
SyntaxHRESULT

SetInt (BMDDeckLinkEncoderConfigurationID cfgID, int64_t *value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The integer value to set into the selected configuration setting.

Return Values

2.5.41.4

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no integer type configuration setting for this operation
corresponding to the given IDeckLinkEncoderConfiguration.

IDeckLinkEncoderConfiguration::GetInt method
The GetInt method gets the current int64_t value of a configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.
SyntaxHRESULT

GetInt (BMDDeckLinkEncoderConfigurationID cfgID, int64_t *value);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

out

The integer value that is set in the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no integer type configuration setting for this operation
corresponding to the given BMDDeckLinkEncoderConfigurationID.

Section 2 — DeckLink API158

2.5.41.5

IDeckLinkEncoderConfiguration::SetFloat method
The SetFloat method sets the current double value of a configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.
SyntaxHRESULT

SetFloat (BMDDeckLinkEncoderConfigurationID cfgID, double *value);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The double value to set into the selected configuration setting.

Return Values

2.5.41.6

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no float type configuration setting for this operation
corresponding to the given BMDDeckLinkEncoderConfigurationID.

IDeckLinkEncoderConfiguration::GetFloat method
The GetFloat method gets the current double value of a configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.
SyntaxHRESULT

GetFloat (BMDDeckLinkEncoderConfigurationID cfgID, double *value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

out

The double value that is set in the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no float type configuration setting for this operation
corresponding to the given BMDDeckLinkEncoderConfigurationID.

Section 2 — DeckLink API

159

2.5.41.7

IDeckLinkEncoderConfiguration::SetString method
The SetString method sets the current string value of a configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.
SyntaxHRESULT

SetString (BMDDeckLinkEncoderConfigurationID cfgID, string *value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The string to set into the selected configuration setting.

Return Values

2.5.41.8

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no string type configuration setting for this operation
corresponding to the given BMDDeckLinkEncoderConfigurationID.

IDeckLinkEncoderConfiguration::GetString method
The GetString method gets the current string value of a configuration setting associated with the given
BMDDeckLinkEncoderConfigurationID.
SyntaxHRESULT

GetString (BMDDeckLinkEncoderConfigurationID cfgID, string *value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

out

The string set in the selected configuration setting. This allocated string
must be freed by the caller when no longer required.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no string type configuration setting for this operation
corresponding to the given BMDDeckLinkEncoderConfigurationID.

Section 2 — DeckLink API160

2.5.41.9

IDeckLinkEncoderConfiguration::GetBytes method
The GetBytes method gets the encoder configuration data in a format represented by the given
BMDDeckLinkEncoderConfigurationID. To determine the size of the buffer required, call GetBytes byinitially passing buffer as NULL. GetBytes will return S_OK and bufferSize will be updated to therequired size.
SyntaxHRESULTetBytes (BMDDeckLinkEncoderConfigurationID cfgID,G
void *buffer, uint32_t *bufferSize);

Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration data format.

bufferout

The buffer in which to return the configuration data, or NULL todetermine the required buffer size.

bufferSize

in, out

The size of the provided buffer. Will be updated to the number of bytes
returned.

Return Values

2.5.42

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no encoder configuration data format corresponding to thegiven BMDDeckLinkEncoderConfigurationID.

E_OUTOFMEMORY

The provided buffer is too small.

IDeckLinkStatus Interface
The IDeckLinkStatus object interface allows querying of status information associated with a DeckLink device.
The DeckLink Status ID section lists the status information and associated identifiers that can be queried using thisobject interface. An IDeckLinkStatus object interface can be obtained from an IDeckLink object interface using
QueryInterface.
An application may be notified of changes to status information by subscribing to the bmdStatusChanged topic using
the IDeckLinkNotification interface. See BMDNotifications for more information.
For an example demonstrating how status information can be queried and monitored, please see the StatusMonitor
sample in the DeckLink SDK.
Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkStatus object interface may be obtained from IDeckLink
using QueryInterface

Section 2 — DeckLink API

161

Public Member Functions

2.5.42.1

MethodDescription

GetFlag

Gets the current boolean value of a status associated with the given
BMDDeckLinkStatusID.

GetIntGets the current int64_t value of a status associated with the given
BMDDeckLinkStatusID.

GetFloat

Gets the current double value of a status associated with the given
BMDDeckLinkStatusID.

GetStringGets the current string value of a status associated with the given
BMDDeckLinkStatusID.

GetBytes

Gets the current byte array value of a status associated with the given
BMDDeckLinkStatusID.

IDeckLinkStatus::GetFlag method
The GetFlag method gets the current boolean value of a status associated with the given BMDDeckLinkStatusID.
SyntaxHRESULT

GetFlag (BMDDeckLinkStatusID statusID, bool *value);Parameters
Name

Direction

Description

statusIDin

The BMDDeckLinkStatusID of the status information item.

value

out

The boolean value corresponding to the statusID.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no flag type status corresponding to the given
BMDDeckLinkStatusID.

E_NOTIMPL

The request is correct however it is not supported by the DeckLink
hardware.

2.5.42.2 IDeckLinkStatus::GetInt method
The GetInt method gets the current int64_t value of a status associated with the given
BMDDeckLinkStatusID.
SyntaxHRESULT

GetInt (BMDDeckLinkStatusID statusID, int64_t *value);Parameters
Name

Direction

Description

statusIDin

The BMDDeckLinkStatusID of the status information item.

value

out

The integer value corresponding to the statusID.

Section 2 — DeckLink API

162

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no integer type status corresponding to the given
BMDDeckLinkStatusID.

E_NOTIMPL

The request is correct however it is not supported by the DeckLink
hardware.

2.5.42.3 IDeckLinkStatus::GetFloat method
The GetFloat method gets the current double value of a status associated with the given
BMDDeckLinkStatusID.
SyntaxHRESULT

GetFloat (BMDDeckLinkStatusID statusID, double *value);Parameters
Name

Direction

Description

statusIDin

The BMDDeckLinkStatusID of the status information item.

value

out

The double value corresponding to the statusID.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no float type status corresponding to the given
BMDDeckLinkStatusID.

E_NOTIMPL

The request is correct however it is not supported by the DeckLink
hardware.

2.5.42.4 IDeckLinkStatus::GetString method
The GetString method gets the current string value of a status associated with the given
BMDDeckLinkStatusID.
SyntaxHRESULT

GetString (BMDDeckLinkStatusIt statusID, string *value);Parameters
Name

Direction

Description

statusIDin

The BMDDeckLinkStatusID of the status information item.

value

out

The string value corresponding to the statusID. This allocated string must be freed by
the caller when no longer required.

Section 2 — DeckLink API

163

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no string type status corresponding to the given BMDDeckLinkStatusID.

E_NOTIMPL

The request is correct however it is not supported by the DeckLink hardware.

2.5.42.5 IDeckLinkStatus::GetBytes method
The GetBytes method gets the current byte array value of a status associated with the given
BMDDeckLinkStatusID.

NOTE If the size of the buffer is not sufficient, bufferSize will be updated to the required buffer size.

SyntaxHRESULT

GetBytes (BMDDeckLinkStatusID statusID, void *buffer, uint32_t *bufferSize);

Parameters
Name

Direction

Description

statusIDin

The BMDDeckLinkStatusID of the status information item.

bufferout

The buffer in which to return the status data.

bufferSize

in, out

The size of the provided buffer. Will be updated to the number of bytes returned.

Return Values

2.5.43

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no byte array type status corresponding to the given BMDDeckLinkStatusID.

IDeckLinkVideoFrameMetadataExtensions Interface
The IDeckLinkVideoFrameMetadataExtensions object interface allows querying of frame metadata
associated with an IDeckLinkVideoFrame.
An IDeckLinkVideoFrameMetadataExtensions object interface may be obtained from an
IDeckLinkVideoFrame object interface using QueryInterface if the IDeckLinkVideoFrame implements
this optional interface.
An IDeckLinkVideoFrame object interface with the bmdFrameContainsHDRMetadata flag may use thisinterface to query the HDR metadata parameters associated with the video frame.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

An IDeckLinkVideoFrameMetadataExtensions
object interface may be obtained from
IDeckLinkVideoFrame using QueryInterface

Section 2 — DeckLink API

164

Public Member Functions

2.5.43.1

MethodDescription

GetIntGets the current int64_t value of a metadata item associatedwith the given BMDDeckLinkFrameMetadataID.

GetFloat

Gets the current double value of a metadata item associatedwith the given BMDDeckLinkFrameMetadataID.

GetFlag

Gets the current boolean value of a metadata item associatedwith the given BMDDeckLinkFrameMetadataID.

GetStringGets the current string value of a metadata item associatedwith the given BMDDeckLinkFrameMetadataID.

GetBytes

Gets a pointer to data of a metadata item associated with thegiven BMDDeckLinkFrameMetadataID.

IDeckLinkVideoFrameMetadataExtensions::GetInt method
The GetInt method gets the current int64_t value of a metadata item associated with the given
BMDDeckLinkFrameMetadataID.
SyntaxHRESULT

GetInt (BMDDeckLinkFrameMetadataID metadataID, int64_t *value);Parameters
Name

Direction

Description

metadataIDin

The BMDDeckLinkFrameMetadataID of the metadata information item.

value

out

The integer value corresponding to the metadataID.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no integer type metadata item corresponding to the given
BMDDeckLinkFrameMetadataID.

2.5.43.2 IDeckLinkVideoFrameMetadataExtensions::GetFloat method
The GetFloat method gets the current double value of a metadata item associated with the given
BMDDeckLinkFrameMetadataID.
SyntaxHRESULT

GetFloat (BMDDeckLinkFrameMetadataID metadataID, double *value);Parameters
Name

Direction

Description

metadataIDin

The BMDDeckLinkFrameMetadataID of the metadata information item.

value

out

The double value corresponding to the metadataID.

Section 2 — DeckLink API

165

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no float type metadata item corresponding to the given
BMDDeckLinkFrameMetadataID.

2.5.43.3 IDeckLinkVideoFrameMetadataExtensions::GetFlag method
The GetFlag method gets the current boolean value of a metadata item associated with the given
BMDDeckLinkFrameMetadataID.
SyntaxHRESULT

GetFlag (BMDDeckLinkFrameMetadataID metadataID, bool* value);Parameters
Name

Direction

Description

metadataIDin

The BMDDeckLinkFrameMetadataID of the metadata information item.

value

out

The boolean value corresponding to the metadataID.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no flag type metadata item corresponding to the given
BMDDeckLinkFrameMetadataID.

2.5.43.4 IDeckLinkVideoFrameMetadataExtensions::GetString method
The GetString method gets the current string value of a metadata item associated with the given
BMDDeckLinkFrameMetadataID.
SyntaxHRESULT

GetString (BMDDeckLinkFrameMetadataID metadataID, string *value);Parameters
Name

Direction

Description

metadataIDin

The BMDDeckLinkFrameMetadataID of the metadata information item.

value

out

The string value corresponding to the metadataID. This allocated string
must be freed by the caller when no longer required.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no string type metadata item corresponding to the given
BMDDeckLinkFrameMetadataID.

Section 2 — DeckLink API

166

2.5.43.5 IDeckLinkVideoFrameMetadataExtensions::GetBytes method
The GetBytes method gets a pointer to data of a metadata item associated with the given
BMDDeckLinkFrameMetadataID. To determine the size of the buffer required, call GetBytes by initiallypassing buffer as NULL. GetBytes will return S_OK and bufferSize will be updated to the required size.
SyntaxHRESULTGetBytes(BMDDeckLinkFrameMetadataID metadataID,
void* buffer,uint32_t* bufferSize)Parameters
Name

Direction

Description

metadataIDin

The BMDDeckLinkFrameMetadataID of the metadata information item.

bufferout

The buffer in which to return the metadata data, or NULL to determine
the required buffer size.

bufferSize

in, out

The size of the provided buffer. Will be updated to the number of bytes
returned.

Return Values

2.5.44

Value

Description

E_INVALIDARG

Parameter bufferSize variable is NULL.

E_OUTOFMEMORY

The provided buffer is too small.

E_UNEXPECTED

There is no byte data type metadata item corresponding to thegiven BMDDeckLinkFrameMetadataID.

E_FAIL

FailureS_OK

Success

IDeckLinkVideoConversion Interface
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.
A reference to an IDeckLinkVideoConversion object interface may be obtained from CoCreateInstanceon platforms with native COM support or from CreateVideoConversionInstance on other platforms.
Public Member Functions
MethodDescription

ConvertFrame

Copies and converts a source frame into a destination frame.

Section 2 — DeckLink API

167

2.5.44.1

IDeckLinkVideoConversion::ConvertFrame method
The ConvertFrame method copies the source frame (srcFrame) to the destination frame (dstFrame). The
frame dimension and pixel format of the video frame will be converted if possible. The return value for thismethod should be checked to ensure that the desired conversion is supported.
The IDeckLinkVideoFrame object for the destination frame, with the desired properties, can be createdusing IDeckLinkOutput::CreateVideoFrame. Alternatively the destination frame can be created bysubclassing IDeckLinkVideoFrame and setting properties directly in the subclassed object.
SyntaxHRESULT

ConvertFrame (IDeckLinkVideoFrame* srcFrame, IDeckLinkVideoFrame* dstFrame)Parameters
Name

Direction

Description

srcFramein

The properties of the source frame

dstFramein

The properties of the destination frame

Return Values

2.5.45

Value

Description

E_FAIL

FailureS_OK

Success

E_NOTIMPL

Conversion not currently supported

E_OUTOFMEMORY

The provided buffer is too small. bufferSize is updated to the required
size.

IDeckLinkHDMIInputEDID Interface
The IDeckLinkHDMIInputEDID object interface allows configuration of EDID parameters, ensuring that an
attached HDMI source outputs a stream that can be accepted by the DeckLink HDMI input.
An IDeckLinkHDMIInputEDID object interface may be obtained from an IDeckLink object interface using
QueryInterface. The EDID items will become visible to an HDMI source connected to a DeckLink HDMI
input after WriteToEDID method is called.
The EDID settings of an IDeckLinkHDMIInputEDID interface remains active while the application holds areference to the interface. Releasing IDeckLinkHDMIInputEDID object interface will restore EDID todefault values.
Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkHDMIInputEDID object interface may be obtained froman IDeckLink object interface using QueryInterface.

Public Member Functions
MethodDescription

SetInt

Sets the current int64_t value of an EDID item associated with thegiven BMDDeckLinkHDMIInputEDIDID.

GetIntGets the current int64_t value of an EDID item associated with thegiven BMDDeckLinkHDMIInputEDIDID.

WriteToEDID

Writes the values for all EDID items to DeckLink hardware

Section 2 — DeckLink API

168

2.5.45.1

IDeckLinkHDMIInputEDID::SetInt method
The SetInt method sets the current int64_t value of an EDID item associated with thegiven BMDDeckLinkHDMIInputEDIDID.
SyntaxHRESULT 	
SetInt (BMDDeckLinkHDMIInputEDIDID cfgID, int64_t value);
Parameters
Name

Direction

Description

cfgID

in

The ID of the EDID item

dstFramein

The integer value to set into the selected EDID item

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no integer type EDID item for this operation corresponding to
the given BMDDeckLinkHDMIInputEDID

2.5.45.2 IDeckLinkHDMIInputEDID::GetInt method
The GetInt method gets the current int64_t value of an EDID item associated with thegiven BMDDeckLinkHDMIInputEDIDID.
SyntaxHRESULT 	
GetInt (BMDDeckLinkHDMIInputEDIDID cfgID, int64_t *value);
Parameters
Name

Direction

Description

cfgID

in

The ID of the EDID item

value

out

The integer value to set into the selected EDID item

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

There is no integer type EDID item for this operation corresponding to
the given BMDDeckLinkHDMIInputEDID.

Section 2 — DeckLink API169

2.5.45.3 IDeckLinkHDMIInputEDID::WriteToEDID method
The WriteToEDID method writes the values for all EDID items to DeckLink hardware.
SyntaxHRESULT 	WriteToEDID ();Return Values

2.5.46

Value

Description

E_FAIL

FailureS_OK

Success

E_ACCESSDENIED

Unable to access DeckLink hardware

IDeckLinkProfileManager Interface
The IDeckLinkProfileManager object interface allows an application to control the profiles for a DeckLink
device that has multiple profiles.
An IDeckLinkProfileManager interface can be obtained from an IDeckLink object interface using
QueryInterface.

NOTE If a DeckLink device only has a single profile, then QueryInterface will fail and return
E_NOINTERFACE.

Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkProfileManager object interface may
be obtained from IDeckLink using QueryInterface

IDeckLinkProfileIterator

IID_IDeckLinkProfileIterator

IDeckLinkProfileManager::GetProfiles returns
an IDeckLinkProfileIterator object interface

IDeckLinkProfile

IID_IDeckLinkProfile

IDeckLinkProfileManager::GetProfile returns
an IDeckLinkProfile object interface

IDeckLinkProfileCallback

IID_ IDeckLinkProfileCallback

An IDeckLinkProfileCallback object interface may beregistered with IDeckLinkProfileManager::SetCallback

Public Member Functions
MethodDescription

GetProfiles

Returns an iterator to enumerate the profiles

GetProfile

Returns the profile object associated with the given identifier

SetCallback

Registers profile change callback

Section 2 — DeckLink API170

2.5.46.1

IDeckLinkProfileManager::GetProfiles method
The GetProfiles method returns an iterator which enumerates the available profiles in the profile grouprepresented by the IDeckLinkProfileManager object.
SyntaxHRESULT

GetProfiles (IDeckLinkProfileIterator *profileIterator);Parameters
Name

Direction

Description

profileIterator

out

Profile iterator. This object must be released by the caller when nolonger required.

Return Values
Value

Description

E_INVALIDARG

Parameter profileIterator variable is NULL.

E_OUTOFMEMORY

Insufficient memory to create the iterator.

S_OK

Success

2.5.46.2 IDeckLinkProfileManager::GetProfile method
The GetProfile method gets the IDeckLinkProfile interface object for a profile with the given
BMDProfileID.
SyntaxHRESULT

GetProfile (BMDProfileID profileID, IDeckLinkProfile *profile);

Parameters
Name

Direction

Description

profileIDin

The ID of the requested profile (see BMDProfileID).

profileout

Pointer to the profile with the matching ID. This object must
be released by the caller when no longer required.

Return Values
Value

Description

E_INVALIDARG

Either the parameter profile variable is NULL or there is no
profile for this DeckLink device with the given BMDProfileID.

S_OK

Success

Section 2 — DeckLink API

171

2.5.46.3 IDeckLinkProfileManager::SetCallback method
The SetCallback method is called to register an instance of an IDeckLinkProfileCallback object. The
registered object facilitates the notification of change in active profile.
SyntaxHRESULT

SetCallback (IDeckLinkProfileCallback *callback);Parameters
Name

Direction

Description

callbackin

The IDeckLinkProfileCallback object to be registered.

Return Values

2.5.47

Value

Description

S_OK

Success

IDeckLinkProfileIterator Interface
The IDeckLinkProfileIterator object interface is used to enumerate the available profiles for the
DeckLink device.
A reference to an IDeckLinkProfileIterator object interface may be obtained by calling GetProfiles on
an IDeckLinkProfileManager object interface.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkProfileManager

IID_IDeckLinkProfileManager

IDeckLinkProfileManager::GetProfiles returns
an IDeckLinkProfileIterator object interface

IDeckLinkProfile

IID_IDeckLinkProfile

IDeckLinkProfile::GetPeers outputs an
IDeckLinkProfileIterator object interface to provide access topeer profiles

IDeckLinkProfile

IID_IDeckLinkProfile

IDeckLinkProfileIterator::Next returns IDeckLinkProfile
interfaces representing each profile for a DeckLink device

Public Member Functions
MethodDescription

Next

Returns an IDeckLinkProfile interface corresponding to anindividual profile for the DeckLink device

Section 2 — DeckLink API172

2.5.47.1

IDeckLinkProfileIterator::Next method
The Next method returns the next available IDeckLinkProfile interface.
SyntaxHRESULT

Next (IDeckLinkProfile *profile);

Parameters
Name

Direction

Description

profileout

Pointer to IDeckLinkProfile interface object or NULL when no
more profiles are available. This object must be released by
the caller when no longer required.

Return Values

2.5.48Value

Description

S_FALSENo (more) profiles found.

S_OK

Success

E_INVALIDARG

Parameter profile variable is NULL.

IDeckLinkProfile Interface
The IDeckLinkProfile object interface represents a supported profile for a sub-device.
When multiple profiles exists for a DeckLink sub-device, the IDeckLinkProfileIterator object interface
enumerates the supported profiles, returning IDeckLinkProfile object interfaces. When switching between
profiles, notification is provided with the IDeckLinkProfileCallback interface object. An application willneed to rescan attributes and display modes after a change in profile.
The current active profile, or the solitary profile when the DeckLink has no IDeckLinkProfileManager
interface, can be obtained from an IDeckLink object interface using QueryInterface.
The GetPeers method returns an IDeckLinkProfileIterator that enumerates the
IDeckLinkProfiles interface objects for the peer sub-devices in the same profile group. When a profile isactivated on a sub-devices with IDeckLinkProfileManager::SetActive method, all peer sub-devices will
be activated with the new profile simultaneously.
Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkProfile object interface may be obtained from
IDeckLink using QueryInterface

IDeckLink

IID_IDeckLink

IDeckLinkProfile::GetDevice returns an IDeckLink object
interface

IDeckLinkProfileIterator

IID_IDeckLinkProfileIterator

IDeckLinkProfileIterator::Next returns an
IDeckLinkProfile object interface for each available profile.

IDeckLinkProfileIterator

IID_IDeckLinkProfileIterator

IDeckLinkProfile::GetPeers returns an
IDeckLinkProfileIterator object interface

IDeckLinkProfileManager

IID_IDeckLinkProfileManager

IDeckLinkProfileManager::GetProfile returns an
IDeckLinkProfile object interface

IDeckLinkProfileCallback

IID_IDeckLinkProfileCallback

An IDeckLinkProfile object interface is passed to boththe IDeckLinkProfileManager::ProfileChanging andIDeckLinkProfileManager::ProfileActivated callbacks

IDeckLinkProfileAttributes

IID_IDeckLinkProfileAttributes

An IDeckLinkProfileAttributes object interface may beobtained from IDeckLinkProfile using QueryInterface

Section 2 — DeckLink API

173

Public Member Functions

2.5.48.1

MethodDescription

GetDevice

Get the DeckLink device associated with this profile

IsActive

Determine whether profile is the active profile of the group

SetActive

Sets the profile to be the active profile of the group

GetPeers

Returns an iterator to enumerate the profiles of its peer subdevices

IDeckLinkProfile::GetDevice method
The GetDevice method returns a reference to the IDeckLink interface associated with the profile.
SyntaxHRESULT

GetDevice (IDeckLink *device);Parameters
Name

Direction

Description

deviceout

The DeckLink device associated with the profile. This object must be
released by the caller when no longer required.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.48.2 IDeckLinkProfile::IsActive method
The IsActive method is called to determine whether the IDeckLinkProfile object is the active profile of the
profile group.
SyntaxHRESULTIsActive (bool *isActive);Parameters
Name

Direction

Description

isActiveout

When returns true, the IDeckLinkProfile is the active profile.

Return Values
Value

Description

E_INVALIDARG

Parameter isActive variable is NULL

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API174

2.5.48.3 IDeckLinkProfile::SetActive method
The SetActive method sets the active profile for the profile group. The active profile is saved to systempreferences immediately so that the setting will persist across system restarts.
SyntaxHRESULTSetActive ();Return Values
Value

Description

E_ACCESSDENIED

Profile group is already in transition

E_FAIL

FailureS_OK

Success

2.5.48.4 IDeckLinkProfile::GetPeers method
The GetPeers method returns an IDeckLinkProfileIterator that enumerates the IDeckLinkProfiles
interface objects for all other sub-devices in the same profile group that share the same BMDProfileID.
SyntaxHRESULT

GetPeers (IDeckLinkProfileIterator *profileIterator);Parameters
Name

Direction

Description

profileIterator

out

Peer profile iterator. This object must be released by the caller when nolonger required.

Return Values

2.5.49Value

Description

E_INVALIDARG

Parameter profileIterator variable is NULL

E_OUTOFMEMORY

Insufficient memory to create iterator

E_FAIL

FailureS_OK

Success

IDeckLinkProfileCallback Interface
The IDeckLinkProfileCallback object interface is a callback class which is called when the profile is about
to change and when a new profile has been activated.
When a DeckLink device has more than 1 profile, an object with an IDeckLinkProfileCallback interface
may be registered as a callback with the IDeckLinkProfileManager object interface by calling
IDeckLinkProfileManager::SetCallback method.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkProfileManager

IID_IDeckLinkProfileManager

An IDeckLinkProfileCallback object interface may beregistered with IDeckLinkProfileManager::SetCallback

IDeckLinkProfile

IID_IDeckLinkProfile

An IDeckLinkProfile object interface is passed to boththe IDeckLinkProfileManager::ProfileChanging andIDeckLinkProfileManager::ProfileActivated callbacks

Section 2 — DeckLink API

175

Public Member Functions

2.5.49.1

MethodDescription

ProfileChanging

Called when the profile is about to change

ProfileActivatedCalled when a new profile has been activated

IDeckLinkProfileCallback::ProfileChanging method
The ProfileChanging method is called when the profile is about to change. This method is abstract in thebase interface and must be implemented by the application developer. The result parameter (required byCOM) is ignored by the caller.

TIP The profile change will not complete until the application returns from the callback. When thestreamsWillBeForcedToStop input is set to true, the new profile is incompatible with the current profile andany active streams will be forcibly stopped on return. The ProfileChanging callback provides the application
the opportunity to stop the streams instead.

SyntaxHRESULTrofileChanging (IDeckLinkProfile *profileToBeActivated,Pbool streamsWillBeForcedToStop);

Parameters
Name

Direction

Description

profileToBeActivatedin

The profile to be activated.

streamsWillBeForcedToStop

in

When true, the profile to be activated is incompatible with the current
profile and the DeckLink hardware will forcibly stop any current streams.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API176

2.5.49.2 IDeckLinkProfileCallback::ProfileActivated method
The ProfileActivated method is called when the new profile has been activated. 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.

TIP When a profile has been activated, rescan appropriate IDeckLinkProfileAttributes and checkdisplay mode support with DoesSupportVideoMode for the new profile.

SyntaxHRESULT

ProfileActivated (IDeckLinkProfile *activatedProfile);

Parameters
Name

Direction

Description

activatedProfilein

The profile that has been activated.

Return Values

2.5.50Value

Description

E_FAIL

FailureS_OK

Success

IDeckLinkMetalScreenPreviewHelper Interface
The IDeckLinkMetalScreenPreviewHelper interface may be used with a simple
IDeckLinkScreenPreviewCallback implementation to provide a Metal-based preview rendering which isdecoupled from the incoming or outgoing video stream being previewed.
A reference to an IDeckLinkMetalScreenPreviewHelper interface may be obtained from a call to
CreateMetalScreenPreviewHelper().
IDeckLinkMetalScreenPreviewHelper is typically used from within a Metal-aware view, such as MTKView.
Typical use of IDeckLinkMetalScreenPreviewHelper is as follows:— Create an IDeckLinkMetalScreenPreviewHelper object interface using
CreateMetalScreenPreviewHelper— Call IDeckLinkMetalScreenPreviewHelper::Initialize with the target device
device = MTLCreateSystemDefaultDevice();deckLinkMetalPreview->Initialize((void*) device);— Create a Metal command queue to process Metal commands.
commandQueue = [device newCommandQueue];— To re-draw the Metal preview, create a Metal command buffer and call
IDeckLinkMetalScreenPreviewHelper::Draw. This will encode the necessary commands to thecommand buffer. Finally present a drawable to the command buffer and commit.
id<MTLCommandBuffer> commandBuffer = [commandQueue commandBuffer];// Note that renderPassDescriptor and drawable objects below are obtained
from the Metal-aware view (eg MTKView).
deckLinkMetalPreview->Draw((void*) commandBuffer, (void*)
renderPassDescriptor, nil);[commandBuffer presentDrawable:drawable];[commandBuffer commit];

Section 2 — DeckLink API

177

— Any graphical overlays or text can be added to the command buffer after call to
IDeckLinkMetalScreenPreviewHelper::Draw.
— Create a subclass of IDeckLinkScreenPreviewCallback which calls
IDeckLinkMetalScreenPreviewHelper::SetFrame from IDeckLinkScreenPreviewCallback::DrawFrame— Register an instance of the IDeckLinkScreenPreviewCallback subclass with
IDeckLinkInput::SetScreenPreviewCallback or IDeckLinkOutput::SetScreenPreviewCallback
as appropriate.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

An IDeckLinkVideoFrame object
interface is set for Metal preview with
IDeckLinkMetalScreenPreviewHelper::SetFrame

Public Member Functions
MethodDescription

Initialize

Initialize Metal Preview.

Draw

Draw the Metal preview.

SetFrame

Set the preview frame to display on the next Draw call.

Set3DPreviewFormat

Set the 3D preview format.

2.5.50.1 IDeckLinkMetalScreenPreviewHelper::Initialize method
The Initialize method should be called to initialize the Metal preview to use the given device.
SyntaxHRESULT

Initialize(void* device)

Parameters
Name

Direction

Description

devicein

Metal device object of type id<MTLDevice>.

Return Values
Value

Description

E_POINTER

Device argument is null

E_INVALIDARG

Device argument is invalid

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API178

2.5.50.2 IDeckLinkMetalScreenPreviewHelper::Draw method
The Draw method encodes commands to a MTLCommandBuffer to draw a frame.
This should typically be called from the drawing method of the Metal-aware view. In the case of MTKView,
this would be the drawRect method when that method has been overridden by a subclass, or
drawInMtkView on the view’s delegate if the subclass doesn’t override it.
IDeckLinkMetalScreenPreviewHelper::Draw must be called with valid MTLCommandBuffer and
MFLRenderPassDescriptor parameters. The viewport parameter is optional, and allows to restrict thedrawing of the preview to a viewport within the view. Pass nil if not required.
Draw and SetFrame allow Metal updates to be decoupled from new frame availability.
SyntaxHRESULT
Draw(void* cmdBuffer,		
void* renderPassDescriptor,
		
void* viewport)
Parameters
Name

Direction

Description

cmdBufferin

Metal command buffer object of type id<MTLCommandBuffer>.

renderPassDescriptor

in

Metal render pass descriptor object of type
MTLRenderPassDescriptor*.

viewportin

Viewport of type MTLViewPort*. Set to nil if not required.

Return Values
Value

Description

E_POINTER

Required argument is null

E_INVALIDARG

Invalid argument received

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API179

2.5.50.3 IDeckLinkMetalScreenPreviewHelper::SetFrame method
The SetFrame method is used to set the preview frame to display on the next call to
IDeckLinkMetalScreenPreviewHelper::Draw.
A null frame pointer can be provided - this will clear the preview.
Depending on the rate and timing of calls to SetFrame and Draw, some frames may not be displayed or
may be displayed multiple times.
SyntaxHRESULT

SetFrame(IDeckLinkVideoFrame* theFrame)

Parameters
Name

Direction

Description

theFrameinVideo Frame to preview

Return Values
Value

Description

E_INVALIDARG

The preview frame is invalid

E_FAIL

FailureS_OK

Success

2.5.50.4 IDeckLinkMetalScreenPreviewHelper::Set3DPreviewFormat method
The Set3DPreviewFormat method is used to set the 3D preview format.
SyntaxHRESULT

Set3DPreviewFormat(BMD3DPreviewFormat previewFormat)

Parameters
Name

Direction

Description

previewFormat

in

The 3D preview format. See BMD3DPreviewFormat for more details.

Return Values
Value

Description

E_INVALIDARG

The preview format is invalid

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

180

2.5.51

IDeckLinkWPFDX9ScreenPreviewHelper Interface
The IDeckLinkWPFDX9ScreenPreviewHelper interface may be used with a simple
IDeckLinkScreenPreviewCallback implementation to provide DirectX based preview rendering in
WPFapplications inferring the D3DImage surface.
A reference to an IDeckLinkWPFDX9ScreenPreviewHelper object is obtained from CoCreateInstance.
For examples demonstrating how to interface an IDeckLinkWPFDX9ScreenPreviewHelper object with
D3DImage in a WPF application, see the CapturePreviewCSharp and SignalGenCSharp samples in the
DeckLink SDK.
Related Interfaces
Interface

Interface ID

Description

IDeckLinkVideoFrameIID_IDeckLinkVideoFrame

An IDeckLinkVideoFrame object
interface is set for DirectX preview with
IDeckLinkWPFDX9ScreenPreviewHelper::SetFrame

Public Member Functions

2.5.51.1

MethodDescription

Initialize

Initialize DirectX device for previewing.

RenderRepaint the DirectX surface.

SetSurfaceSize

Set the size of render surface.

SetFrame

Set the preview frame for display.

Set3DPreviewFormat

Set the 3D preview format.

GetBackBuffer

Get reference to renderer back-buffer

IDeckLinkWPFDX9ScreenPreviewHelper::Initialize method
The Initialize method prepares a DirectX 9 3D device to be used by the DeckLink API’s WPF
preview helper.
SyntaxHRESULT

Initialize()

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

181

2.5.51.2 IDeckLinkWPFDX9ScreenPreviewHelper::Render method
The Render method should be called whenever the preview frame needs to be repainted. The frames tobe displayed should be provided to IDeckLinkWPFDX9ScreenPreviewHelper::SetFrame.
SyntaxHRESULTRender()Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.51.3 IDeckLinkWPFDX9ScreenPreviewHelper::SetSurfaceSize method
The SetSurfaceSize method is used to set the size of render surface.
SyntaxHRESULT
SetSurfaceSize(uint32_t width,		
uint32_t height)
Parameters
Name

Direction

Description

width

in

Width of surface in pixels.

heightin

Height of surface in pixels.

Return Values
Value

Description

E_INVALIDARG

Invalid value for parameters width or height

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

182

2.5.51.4

IDeckLinkWPFDX9ScreenPreviewHelper::SetFrame method
The SetFrame method will load a 2D or 3D IDeckLinkVideoFrame into a texture. This method is used to
set the preview frame to display on the next call to IDeckLinkWPFDX9ScreenPreviewHelper::Render.
Depending on the rate and timing of calls to SetFrame and Render, some frames may not be displayed or
may be displayed multiple times.
SyntaxHRESULT

SetFrame(IDeckLinkVideoFrame* theFrame)

Parameters
Name

Direction

Description

theFramein

The video frame to preview.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.5.51.5 IDeckLinkWPFDX9ScreenPreviewHelper::Set3DPreviewFormat method
The Set3DPreviewFormat method is used to set the 3D preview format.
SyntaxHRESULT

Set3DPreviewFormat(BMD3DPreviewFormat previewFormat)

Parameters
Name

Direction

Description

previewFormat

in

The 3D preview format. See BMD3DPreviewFormat for more details.

Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API

183

2.5.51.6 IDeckLinkWPFDX9ScreenPreviewHelper::GetBackBuffer method
The GetBackBuffer method outputs the renderer back buffer than can be copied to front buffer in WPF
render thread.
SyntaxHRESULT GetBackBuffer(void** backBuffer)
Parameters
Name

Direction

Description

backBuffer

out

Pointer to renderer back-buffer.

Return Values
Value

Description

E_POINTER

The backBuffer parameter is invalid.

E_FAIL

FailureS_OK

Success

2.6

Streaming Interface Reference

2.6.1

IBMDStreamingDiscovery Interface
The IBMDStreamingDiscovery object interface is used to install or remove the callback for receiving
streaming device discovery notifications.
A reference to an IBMDStreamingDiscovery object interface may be obtained from CoCreateInstance on
platforms with native COM support or from CreateBMDStreamingDiscoveryInstance on other platforms.
Public Member Functions
MethodDescription

InstallDeviceNotifications

Install device notifications callback

UninstallDeviceNotifications

Remove device notifications callback

Section 2 — DeckLink API

184

2.6.1.1

IBMDStreamingDiscovery::InstallDeviceNotifications method
The InstallDeviceNotifications method installs the callback which will be called when a new streaming
device becomes available.

NOTE Only one callback may be installed at a time.

SyntaxHRESULT nstallDeviceNotifications
I(IBMDStreamingDeviceNotificationCallback* theCallback);Parameters
Name

Direction

Description

theCallbackinCallback object implementing the
IBMDStreamingDeviceNotificationCallback object interface

Return Values

2.6.1.2

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

The callback parameter is invalid.

E_UNEXPECTED

An unexpected internal error has occurred.

IBMDStreamingDiscovery::UninstallDeviceNotifications method
The UninstallDeviceNotifications method removes the device notifications callback.
SyntaxHRESULTUninstallDeviceNotifications ();Return Values

2.6.2

Value

Description

S_OK

Success

E_UNEXPECTED

An unexpected internal error has occurred.

IBMDStreamingDeviceNotificationCallback Interface
The IBMDStreamingDeviceNotificationCallback object interface is a callback class which is called whena streaming device arrives, is removed or undergoes a mode change.
Related Interfaces
Interface

Interface ID

Description

IBMDStreamingDiscovery

IID_IBMDStreamingDiscovery

An IBMDStreamingDeviceNotificationCallback
object interface may be installed withIBMDStreamingDiscovery::InstallDeviceNotifications

Section 2 — DeckLink API

185

Public Member Functions

2.6.2.1

MethodDescription

StreamingDeviceArrived

Streaming device arrived

StreamingDeviceRemoved

Streaming device removed

StreamingDeviceModeChanged

Streaming device mode changed

IBMDStreamingDeviceNotificationCallback::StreamingDeviceArrived method
The StreamingDeviceArrived method is called when a new streaming device becomes available.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTStreamingDeviceArrived (IDeckLink* device);Parameters
Name

Direction

Description

deviceinstreaming device

Return Values

2.6.2.2

Value

Description

E_FAIL

FailureS_OK

Success

IBMDStreamingDeviceNotificationCallback::StreamingDeviceRemoved
methodThe StreamingDeviceRemoved method is called when a streaming device is removed.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTStreamingDeviceRemoved (IDeckLink* device);Parameters
Name

Direction

Description

deviceinstreaming device

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

186

2.6.2.3

IBMDStreamingDeviceNotificationCallback::StreamingDeviceModeChanged
methodThe StreamingDeviceModeChanged method is called when a streaming device’s mode has changed.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTtreamingDeviceModeChanged (IDeckLink* device,S
BMDStreamingDeviceMode mode);

Parameters
Name

Direction

Description

deviceinstreaming device

mode

in

new streaming device mode after the mode change occurred

Return Values

2.6.3

Value

Description

E_FAIL

FailureS_OK

Success

IBMDStreamingVideoEncodingMode Interface
The IBMDStreamingVideoEncodingMode object interface represents a streaming video encoding mode.
The encoding mode encapsulates all the available encoder settings such as video codec settings andaudio codec settings. To make changes to encoder settings use the
IBMDStreamingMutableVideoEncodingMode object interface obtained via theCreateMutableVideoEncodingMode method.
Related Interfaces
Interface

Interface ID

Description

IBMDStreamingVideo
EncodingMode
PresetIterator

IID_IBMDStreaming
VideoEncodingMode
PresetIterator

IBMDStreamingVideoEncodingModePresetIterator::Next
returns an IBMDStreamingVideoEncodingMode object
interface for each available video encoding mode.

IBMDStreamingMutable
VideoEncodingMode

IID_IBMDStreamingMutable
VideoEncodingMode

A mutable subclass of IBMDStreamingVideoEncodingMode
may be created using CreateMutableVideoEncodingMode

Public Member Functions
MethodDescription

GetNameGet the name describing the video encoding mode.

GetPresetID

Get the unique ID representing the video encoding mode.

GetSourcePositionX

Get the x coordinate of the origin of the video source
rectangle.

GetSourcePositionY

Get the y coordinate of the origin of the video source
rectangle.

GetSourceWidth

Get the width of the video source rectangle.

GetSourceHeight

Get the height of the video source rectangle.

Section 2 — DeckLink API

187

Public Member Functions

2.6.3.1

MethodDescription

GetDestWidth

Get the width of the video destination rectangle.

GetDestHeight

Get the height of the video destination rectangle.

GetFlag

Get the current value of a boolean encoding mode setting.

GetInt

Get the current value of a int64_t encoding mode setting.

GetFloat

Get the current value of a double encoding mode setting.

GetStringGet the current value of a string encoding mode setting.

CreateMutableVideoEncodingMode

Create a mutable copy of the
IBMDStreamingVideoEncodingMode object interface.

IBMDStreamingVideoEncodingMode::GetName method
The GetName method returns a string describing the video encoding mode.
SyntaxHRESULT

GetName (string name);Parameters
Name

Direction

Description

name

out

Video encoding name. This allocated string must be freed by the callerwhen no longer required.

Return Values

2.6.3.2

Value

Description

E_FAIL

FailureS_OK

Success

E_POINTER

The name parameter is invalid.

IBMDStreamingVideoEncodingMode::GetPresetID method
The GetPresetID method returns the unique ID representing the preset video mode.
Syntaxunsigned int

GetPresetID ();Return Values
Value

Description

idUnique ID of preset video mode.

Section 2 — DeckLink API

188

2.6.3.3

IBMDStreamingVideoEncodingMode::GetSourcePositionX method
The GetSourcePositionX method returns the x coordinate of the origin of the source rectangle used for
encoding video.
Syntaxunsigned int

GetSourcePositionX ();Return Values

2.6.3.4

Value

Description

xPosition

The x coordindate in pixels for source rectangle origin.

IBMDStreamingVideoEncodingMode::GetSourcePositionY method
The GetSourcePositionY method returns the y coordinate of the origin of the source rectangle used for
encoding video.
Syntaxunsigned int

GetSourcePositionY ();Return Values

2.6.3.5

Value

Description

yPosition

The y coordindate in pixels for source rectangle origin.

IBMDStreamingVideoEncodingMode::GetSourceWidth method
The GetSourceWidth method returns the width of the source rectangle used for encoding video.
Syntaxunsigned int

GetSourceWidth ();Return Values

2.6.3.6

Value

Description

width

Width in pixels of the source rectangle.

IBMDStreamingVideoEncodingMode::GetSourceHeight method
The GetSourceHeight method the height of the source rectangle used for encoding video.
Syntaxunsigned int

GetSourceHeight ();Return Values
Value

Description

heightHeight in pixels of the source rectangle.

Section 2 — DeckLink API

189

2.6.3.7

IBMDStreamingVideoEncodingMode::GetDestWidth method
The GetDestWidth method returns the width of the destination rectangle used when encoding video. If
the destination rectangle is different to the source rectangle the video will be scaled when encoding.
Syntaxunsigned int

GetDestWidth ();Return Values

2.6.3.8

Value

Description

width

Width in pixels of the destination rectangle.

IBMDStreamingVideoEncodingMode::GetDestHeight method
The GetDestHeight method returns the height of the destination rectangle used when encoding video. If
the destination rectangle is different to the source rectangle the video will be scaled when encoding.
Syntaxunsigned int

GetDestHeight ();Return Values

2.6.3.9

Value

Description

heightHeight in pixels of the destination rectangle.

IBMDStreamingVideoEncodingMode::GetFlag method
The GetFlag method gets the current value of the boolean configuration setting associatedwith the given BMDStreamingEncodingModePropertyID.
SyntaxHRESULT

GetFlag(BMDStreamingEncodingModePropertyID cfgID, boolean* value);Parameters
Name

Direction

Description

cfgID

in

BMDStreamingEncodingModePropertyID to get flag value.

value

out

The value corresponding to cfgID.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

Section 2 — DeckLink API

190

2.6.3.10 IBMDStreamingVideoEncodingMode::GetInt method
The GetInt method gets the current value of the int64_t configuration setting associated with the given
BMDStreamingEncodingModePropertyID.
SyntaxHRESULT

GetInt (BMDStreamingEncodingModePropertyID cfgID, int64_t* value);Parameters
Name

Direction

Description

cfgID

in

BMDStreamingEncodingModePropertyID to get integer value.

value

out

The value corresponding to cfgID.

Return Values

2.6.3.11

Value

Description

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

IBMDStreamingVideoEncodingMode::GetFloat method
The GetFloat gets the current value of the double configuration setting associated with the given
BMDStreamingEncodingModePropertyID.
SyntaxHRESULT

GetFloat (BMDStreamingEncodingModePropertyID cfgID, double* value);Parameters
Name

Direction

Description

cfgID

in

BMDStreamingEncodingModePropertyID to get double value.

value

out

The value corresponding to cfgID.

Return Values
Value

Description

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

Section 2 — DeckLink API

191

2.6.3.12

IBMDStreamingVideoEncodingMode::GetString method
The GetString current value of the string configuration setting associated with the given
BMDStreamingEncodingModePropertyID.
SyntaxHRESULT

GetString (BMDStreamingEncodingModePropertyID cfgID, string value);Parameters
Name

Direction

Description

cfgID

in

BMDStreamingEncodingModePropertyID to get string value.

value

out

The value corresponding to cfgID. This allocated string must be freed
by the caller when no longer required.

Return Values

2.6.3.13

Value

Description

S_OK

Success

E_INVALIDARG

One or more parameters are invalid.

E_OUTOFMEMORY

Unable to allocate memory for string.

IBMDStreamingVideoEncodingMode::CreateMutableVideoEncodingMode method
The CreateMutableVideoEncodingMode method creates a new object interface which is a mutable copy of the
IBMDStreamingVideoEncodingMode object interface.
IBMDStreamingMutableVideoEncodingMode is a subclass of IBMDStreamingVideoEncodingMode and inherits all its methods.
It provides additional methods to change settings for the encoding of video and audio streams.
SyntaxHRESULT reateMutableVideoEncodingMode
C(IBMDStreamingMutableVideoEncodingMode* newEncodingMode);

Parameters
Name

Direction

Description

newEncodingModeout

A new mutable encoding mode object interface.

Return Values
Value

Description

S_OK

Success

E_POINTER

The newEncodingMode parameter is invalid.

E_OUTOFMEMORY

Unable to allocate memory for new object interface.

Section 2 — DeckLink API

192

2.6.4IBMDStreamingMutableVideoEncodingMode Interface
The IBMDStreamingMutableVideoEncodingMode object interface represents a mutable streaming video
encoding mode.
Methods are provided to set video codec settings and audio codec settings. Use this object interface if you wish to
perform cropping or scaling of the input video frame, adjust the video or audio bit rate and to change other video or
audio codec settings.
Related Interfaces
Interface

Interface ID

Description

IBMDStreamingVideo
EncodingMode

IID_IBMDStreamingVideo
EncodingMode

An IBMDStreamingMutableVideoEncodingModeobject interface may be created from an
IBMDStreamingVideoEncodingMode interface object using
its CreateMutableVideoEncodingMode method.

Public Member Functions

2.6.4.1

MethodDescription

SetSourceRect

Set the video source rectangle.

SetDestSize

Set the size of the video destination rectangle.

SetFlag

Set the value for a boolean encoding mode setting.

SetInt

Set the value for an int64_t encoding mode setting.

SetFloat

Set the value for a double encoding mode setting.

SetStringSet the value for a string encoding mode setting.

IBMDStreamingMutableVideoEncodingMode::SetSourceRect method
The SetSourceRect method sets the source rectangle used for encoding video.
Cropping of the input video frame can be achieved by using a source rectangle that is different to the
input video frame dimensions.
When no source rectangle is set, the source rectangle of the parent IBMDStreamingVideoEncodingModeobject interface will be used by the encoder.
SyntaxHRESULTetSourceRect (uint32_t posX, uint32_t posY,
S
uint32_t width, uint32_t height);

Parameters
Name

Direction

Description

posX

in

X coordinate of source rectangle origin.

posY

in

Y coordinate of source rectangle origin.

width

in

Width of source rectangle.

heightin

Height of source rectangle.

Return Values
Value

Description

S_OK

Success

Section 2 — DeckLink API193

2.6.4.2

IBMDStreamingMutableVideoEncodingMode::SetDestSize method
The SetDestSize method sets the destination rectangle used for encoding video.
When the destination rectangle size is set to a different size to the source rectangle size, scaling will be
performed by the encoder.
When no destination rectangle size is set, the source rectangle size of the parent
IBMDStreamingVideoEncodingMode object interface will be used by the encoder.
SyntaxHRESULT

SetDestSize (uint32_t width, uint32_t height);Parameters
Name

Direction

Description

width

in

Width of destination rectangle.

heightin

Height of destination rectangle.

Return Values

2.6.4.3

Value

Description

S_OK

Success

IBMDStreamingMutableVideoEncodingMode::SetFlag method
The SetFlag method sets a boolean value into the configuration setting associated with the given
BMDStreamingEncodingModePropertyID.
SyntaxHRESULT

SetFlag (BMDStreamingEncodingModePropertyID cfgID, boolean value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The boolean value to set into the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

One or more parameters are invalid.

Section 2 — DeckLink API

194

2.6.4.4

IBMDStreamingMutableVideoEncodingMode::SetInt method
The SetInt method sets an int64_t value into the configuration setting associated with the given
BMDStreamingEncodingModePropertyID.
SyntaxHRESULT

SetInt (BMDStreamingEncodingModePropertyID cfgID, int64_t value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The integer value to set into the selected configuration setting.

Return Values

2.6.4.5

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

One or more parameters are invalid.

IBMDStreamingMutableVideoEncodingMode::SetFloat method
The SetFloat method sets a double value into the configuration setting associated with the given
BMDStreamingEncodingModePropertyID.
SyntaxHRESULT

SetFloat (BMDStreamingEncodingModePropertyID cfgID, double value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The double value to set into the selected configuration setting.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

One or more parameters are invalid.

Section 2 — DeckLink API

195

2.6.4.6

IBMDStreamingMutableVideoEncodingMode::SetString method
The SetString method sets a string value into the configuration setting associated with the given
BMDStreamingEncodingModePropertyID.
SyntaxHRESULT

SetString (BMDStreamingEncodingModePropertyID cfgID, string value);Parameters
Name

Direction

Description

cfgID

in

The ID of the configuration setting.

value

in

The string value to set into the selected configuration setting.

Return Values

2.6.5

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

One or more parameters are invalid.

IBMDStreamingVideoEncodingMode::PresetIteratorInterface
The IBMDStreamingVideoEncodingModePresetIterator object interface is used to enumerate the available
preset video encoding modes.
A device may have a number of preset encoding modes. These are convenient encoding modes which can beused to encode video and audio into formats suitable for a number of commonly available playback devices.
A reference to an IBMDStreamingVideoEncodingModePresetIterator object interface may be obtained from an
IBMDStreamingDeviceInput object interface using the GetVideoEncodingModePresetIterator method.
Related Interfaces
Interface

Interface ID

Description

IBMDStreaming
DeviceInput

IID_
IBMDStreaming
DeviceInput

IBMDStreamingDeviceInput::GetVideoEncodingModePresetIterator returns
an IBMDStreamingVideoEncodingModePresetIterator object interface.

Public Member Functions
MethodDescription

Next

Returns a pointer to an IBMDStreamingVideoEncodingMode object interface
for an available preset encoding mode.

Section 2 — DeckLink API

196

2.6.5.1

IBMDStreamingVideoEncodingModePresetIterator::Next method
The Next method returns the next available IBMDStreamingVideoEncodingModeobject interface.
SyntaxHRESULTNext (IBMDStreamingVideoEncodingMode* videoEncodingMode);

Parameters
Name

Direction

Description

videoEncodingMode

out

IBMDStreamingVideoEncodingMode object interface or NULL when
no more video encoding modes are available.

Return Values

2.6.6

Value

Description

S_OK

Success

S_FALSENo (more) preset encoding modes are available.

E_POINTER

The videoEncodingMode parameter is invalid.

IBMDStreamingDeviceInput Interface
The IBMDStreamingDeviceInput object interface represents a physical streaming video encoder device.
Related Interfaces
Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IBMDStreamingDeviceInput object interface may be obtained from
IDeckLink using QueryInterface.

IBMDStreaming
DeviceNotification
Callback

IID_IBMDStreaming
DeviceNotification
Callback

IBMDStreamingDeviceNotificationCallback::StreamingDeviceArrived
returns an IDeckLink object interface representing a streaming video
encoder device

Public Member Functions
MethodDescription

DoesSupportVideoInputMode

Indicates whether a video input mode is supported by the device

GetVideoInputModeIterator

Get an iterator to enumerate available video input modes

SetVideoInputMode

Set a display mode as the device’s video input mode

GetCurrentDetectedVideoInputMode

Get the current video input mode detected by the device

GetVideoEncodingMode

Get the currently configured video encoding mode

GetVideoEncodingModePresetIterator

Get an iterator to enumerate available video encoding mode presets

DoesSupportVideoEncodingMode

Indicates whether a video encoding mode is supported by the device

SetVideoEncodingMode

Set a video encoding mode as the device’s current video encoding mode

StartCapture

Start a video encoding capture

StopCapture

Stop a video encoding capture

SetCallback

Set a callback for receiving new video and audio packets

Section 2 — DeckLink API197

2.6.6.1

IBMDStreamingDeviceInput::DoesSupportVideoInputMode method
The DoesSupportVideoInputMode method indicates whether a given video input mode is supported on
the device.
SyntaxHRESULT

DoesSupportVideoInputMode (BMDDisplayMode inputMode, boolean* result);Parameters
Name

Direction

Description

inputModein

BMDDisplayMode to test for input support.

resultout

Boolean value indicating whether the mode is supported.

Return Values

2.6.6.2

Value

Description

S_OK

Success

E_POINTER

The result parameter is invalid.

E_INVALIDARG

The inputMode parameter is invalid

IBMDStreamingDeviceInput::GetVideoInputModeIterator method
The GetVideoInputModeIterator method returns an iterator which enumerates the available video
input modes.
SyntaxHRESULT

GetVideoInputModeIterator (IDeckLinkDisplayModeIterator* iterator);Parameters
Name

Direction

Description

iterator

out

Display mode iterator

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_POINTER

The iterator parameter is invalid.

Section 2 — DeckLink API

198

2.6.6.3

IBMDStreamingDeviceInput::SetVideoInputMode method
The SetVideoInputMode method configures the device to use the specified video display mode for input.
SyntaxHRESULT

SetVideoInputMode (BMDDisplayMode inputMode);Parameters
Name

Direction

Description

inputModein

Display mode to set as the input display mode

Return Values

2.6.6.4

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

The inputMode parameter is invalid.

IBMDStreamingDeviceInput::GetCurrentDetectedVideoInputMode method
The GetCurrentDetectedVideoInputMode method returns the current video input display mode as
detected by the device.
SyntaxHRESULT

GetCurrentDetectedVideoInputMode (BMDDisplayMode* detectedMode);Parameters
Name

Direction

Description

detectedMode

out

Display mode the device detected for video input

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

The detectedMode parameter is invalid.

Section 2 — DeckLink API199

2.6.6.5

IBMDStreamingDeviceInput::GetVideoEncodingMode method
The GetVideoEncodingMode method returns the currently configured video encoding mode.
SyntaxHRESULT

GetVideoEncodingMode (IBMDStreamingVideoEncodingMode* encodingMode);Parameters
Name

Direction

Description

encodingMode

out

Current video encoding mode

Return Values

2.6.6.6

Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

The encodingMode parameter is invalid.

IBMDStreamingDeviceInput::GetVideoEncodingModePresetIterator method
The GetVideoEncodingModePresetIterator method returns an iterator which enumerates the available
video encoding mode presets.
Different video display modes may have different encoding mode presets.
SyntaxHRESULT

etVideoEncodingModePresetIterator (BMDDisplayMode inputMode,G
IBMDStreamingVideoEncodingModePresetIterator* iterator);

Parameters
Name

Direction

Description

inputModein

The DisplayMode to iterate encoding mode presets for

iteratoroutVideo encoding mode preset iterator

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

The iterator parameter is invalid.

Section 2 — DeckLink API

200

2.6.6.7

IBMDStreamingDeviceInput::DoesSupportVideoEncodingMode method
The DoesSupportVideoEncodingMode method indicates whether a given video encoding mode issupport by the device for the given input display mode. Modes may be supported, not supported or
supported with changes. If a mode is supported with changes, the changed mode will be returned by thechangedEncodingMode parameter.
SyntaxHRESULToesSupportVideoEncodingMode (BMDDisplayMode inputMode,D
IBMDStreamingVideoEncodingMode* encodingMode, BMDStreamingEncodingSupport*
result, IBMDStreamingVideoEncodingMode* changedEncodingMode);

Parameters
Name

Direction

Description

inputModein

Display mode to be used with the video encoding mode

encodingModeinVideo encoding mode to be tested for support

resultout

Indicates whether the mode is supported, not supported or supportedwith changes

changedEncodingMode

out

Changed encoding mode when the mode is supported with changes

Return Values

2.6.6.8

Value

Description

E_FAIL

FailureS_OK

Success

E_POINTER

One or more out parameters are invalid

E_INVALIDARG

The encodingMode parameter is invalid

IBMDStreamingDeviceInput::SetVideoEncodingMode method
The SetVideoEncodingMode method sets the given video encoding mode as the device’s current video
encoding mode. It is necessary to set a video encoding mode before calling the StartCapture method.
SyntaxHRESULT

SetVideoEncodingMode (IBMDStreamingVideoEncodingMode* encodingMode);Parameters
Name

Direction

Description

encodingModeinVideo encoding mode to be used by the device.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_INVALIDARG

The encodingMode parameter is invalid

Section 2 — DeckLink API

201

2.6.6.9

IBMDStreamingDeviceInput::StartCapture method
The StartCapture method starts a capture on the device using the current video encoding mode.
If a callback implementing the IBMDStreamingH264InputCallback object interface has been set by the
SetCallback method, calls will be made as new compressed video and audio packets are made available
by the device.
SyntaxHRESULT

StartCapture ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

2.6.6.10 IBMDStreamingDeviceInput::StopCapture method
The StopCapture method stops a capture if a capture is currently in progress.
SyntaxHRESULTStopCapture ();Parameters
none.
Return Values

2.6.6.11

Value

Description

E_FAIL

FailureS_OK

Success

IBMDStreamingDeviceInput::SetCallback method
The SetCallback method configures a callback which will be called for new input from the device or when
the device input changes.
An object shall be passed implementing the IBMDStreamingH264InputCallback object interface as the
callback to receive callbacks An existing callback can be removed by passing NULL in the callback parameter.
SyntaxHRESULT

SetCallback (IUnknown* theCallback);Parameters
Name

Direction

Description

theCallbackincallback object implementing the IUnknown object interface

Section 2 — DeckLink API

202

Return Values

2.6.7

Value

Description

E_FAIL

FailureS_OK

Success

IBMDStreamingH264InputCallback Interface
The IBMDStreamingH264InputCallback object interface is a callback class which is called when
encoded video and audio packets are available or when the video input to the streaming device changes.
Once a capture has been started with the IBMDStreamingDeviceInput::StartCapture method,compressed video and audio packets will become available asynchronously.
This callback object interface can also be used to detect changes to the video input display mode andchanges to the video input connector, whether or not a capture is in progress.
Related Interfaces
Interface

Interface ID

Description

IBMDStreamingDeviceInput

IID_IBMDStreaming
DeviceInput

An IBMDStreamingH264InputCallback
object interface may be installed withIBMDStreamingDeviceInput::SetCallback

Public Member Functions

2.6.7.1

MethodDescription

H264NALPacketArrived

Called when a NAL video packet is available

H264AudioPacketArrived

Called when an audio packet is available

MPEG2TSPacketArrived

Called when a transport stream packet is available

H264VideoInputConnectorScanningChanged

Called when the video input connect scanning mode has changed

H264VideoInputConnectorChanged

Called when the video input connect connector has changed

H264VideoInputModeChanged

Called when the video input display mode has changed

IBMDStreamingH264InputCallback::H264NALPacketArrived method
The H264NALPacketArrived method is called when an IBMDStreamingH264NALPacket becomes
available from the streaming device while a capture is in progress.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTH264NALPacketArrived(IBMDStreamingH264NALPacket* nalPacket);Parameters
Name

Direction

Description

nalPacketin

NAL packet containing compressed video.

Section 2 — DeckLink API

203

Return Values

2.6.7.2

Value

Description

E_FAIL

FailureS_OK

Success

IBMDStreamingH264InputCallback::H264AudioPacketArrived method
The H264AudioPacketArrived method is called when an IBMDStreamingAudioPacket becomes
available from the streaming device while a capture is in progress.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTH264AudioPacketArrived (IBMDStreamingAudioPacket* audioPacket);Parameters
Name

Direction

Description

audioPacket

in

Audio packet containing compressed audio.

Return Values

2.6.7.3

Value

Description

E_FAIL

FailureS_OK

Success

IBMDStreamingH264InputCallback::MPEG2TSPacketArrived method
The MPEG2TSPacketArrived method is called when an IBMDStreamingMPEG2TSPacket becomes
available from the streaming device while a capture is in progress.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTMPEG2TSPacketArrived (IBMDStreamingMPEG2TSPacket* tsPacket);Parameters
Name

Direction

Description

tsPacketin

MPEG transport stream packet containing video or audio data.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

204

2.6.7.4

IBMDStreamingH264InputCallback::H264VideoInputConnectorScanning
Changed method
The H264VideoInputConnectorScanningChanged method is called when the input connect scanningmode has changed.
This method will be called independently of capture state.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTH264VideoInputConnectorScanningChanged ();Parameters
none.
Return Values

2.6.7.5

Value

Description

E_FAIL

FailureS_OK

Success

IBMDStreamingH264InputCallback::H264VideoInputConnectorChanged
methodThe H264VideoInputConnectorChanged method is called when the streaming device detects a change
to the input connector.
This method will be called independently of capture state.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTH264VideoInputConnectorChanged ();Parameters
none.
Return Values
Value

Description

E_FAIL

FailureS_OK

Success

Section 2 — DeckLink API

205

2.6.7.6

IBMDStreamingH264InputCallback::H264VideoInputModeChanged method
The H264VideoInputModeChanged method is called when the streaming device detects a change to thevideo input display mode.
This method will be called independently of capture state.
The result parameter (required by COM) is ignored by the caller.
SyntaxHRESULTH264VideoInputModeChanged ();Parameters
none.
Return Values

2.6.8

Value

Description

E_FAIL

FailureS_OK

Success

IBMDStreamingH264NALPacket Interface
The IBMDStreamingH264NALPacket object interface represents an MPEG-4 AVC/H.264 Network
Adaptation Layer (NAL) packet.
Objects with an IBMDStreamingH264NALPacket object interface are passed to
the IBMDStreamingH264InputCallback::H264NALPacketArrived callback.
The MPEG-4 AVC/H.264 NAL packet contains the compressed H.264 video bitstream which can bepassed to a suitable H.264 video decoder for decoding and display. For some applications it may be moreconvenient to process NAL video packets instead of processing video carried in transport stream packets.
Related Interfaces
Interface

Interface ID

Description

IBMDStreaming
H264InputCallback

IID_IBMDStreaming
H264InputCallback

New MPEG-4 AVC/H.264 NAL packets are passed to the
IBMDStreamingH264InputCallback::H264NALPacketArrived
callback

Public Member Functions
MethodDescription

GetPayloadSize

Get number of bytes in the NAL packet

GetBytes

Get pointer to NAL packet data

GetBytesWithSizePrefix

Get pointer to NAL packet data prefixed by a 32bit size value

GetDisplayTime

Get display time for the NAL packet

Section 2 — DeckLink API

206

2.6.8.1

IBMDStreamingH264NALPacket::GetPayloadSize method
The GetPayloadSize method gets the number of bytes in the NAL packet.
Syntaxlong

GetPayloadSize ();Return Values

2.6.8.2

Value

Description

Count

NAL packet size in bytes

IBMDStreamingH264NALPacket::GetBytes method
The GetBytes method returns a pointer to the data buffer of the NAL packet.
SyntaxHRESULT

GetBytes (void* buffer);Parameters
Name

Direction

Description

bufferout

Pointer to NAL packet data buffer – only valid while object remains
valid.

Return Values

2.6.8.3

Value

Description

S_OK

Success

E_POINTER

The parameter is invalid.

IBMDStreamingH264NALPacket::GetBytesWithSizePrefix method
The GetBytesWithSizePrefix method returns a pointer to a data buffer starting with a 32bit unsigned
integer containing the size of the NAL packet followed by the data buffer of the NAL packet. This
arrangement may be required by some video decoders.

NOTE The size of the data buffer returned by GetBytesWithSizePrefix is 4 bytes larger than the size ofthe data buffer returned by GetBytes.

SyntaxHRESULT

GetBytesWithSizePrefix (void* buffer);Parameters
Name

Direction

Description

bufferout

Pointer to NAL packet data buffer prefixed by size value – only valid
while object remains

Return Values
Value

Description

S_OK

Success

E_POINTER

The parameter is invalid.

Section 2 — DeckLink API

207

2.6.8.4

IBMDStreamingH264NALPacket::GetDisplayTime method
The GetDisplayTime method returns the time at which to display the video contained in the NAL packet.
The display time is in units of the requested time scale.
SyntaxHRESULT

GetDisplayTime (uint64_t requestedTimeScale, uint64_t* displayTime);Parameters
Name

Direction

Description

requestedTimeScaleinTime scale for the displayTime

displayTimeout

Time at which to display the video

Return Values

2.6.9

Value

Description

S_OK

Success

E_POINTER

The displayTime parameter is invalid.

IBMDStreamingAudioPacket Interface
The IBMDStreamingAudioPacket object interface represents an audio packet.
Objects with an IBMDStreamingAudioPacket object interface are passed to the
IBMDStreamingH264InputCallback::H264AudioPacketArrived callback.
The audio packet can contain compressed audio, such as MPEG-2 AAC audio, which can be passed to asuitable audio decoder for decoding and playback. For some applications it may be more convenient toprocess audio packets instead of processing audio carried in transport stream packets.
Related Interfaces
Interface

Interface ID

Description

IBMDStreaming
H264InputCallback

IID_IBMDStreaming
H264InputCallback

New audio packets are passed to the
IBMDStreamingH264InputCallback::H264AudioPacketArrived
callback

Public Member Functions
MethodDescription

GetCodec

Get the codec describing the type of audio in the audio packet

GetPayloadSize

Get number of bytes in the audio packet

GetBytes

Get pointer to audio packet data

GetPlayTime

Get the play time for the audio in the audio packet

Section 2 — DeckLink API

208

2.6.9.1

IBMDStreamingAudioPacket::GetCodec method
The GetCodec method returns the codec describing the audio in the packet.
SyntaxBMDStreamingAudioCodec

GetCodec ();Return Values

2.6.9.2

Value

Description

Codec

The codec for the audio in the packet.

IBMDStreamingAudioPacket::GetPayloadSize method
The GetPayloadSize method gets the number of bytes in the audio packet.
Syntaxlong

GetPayloadSize ();Return Values

2.6.9.3

Value

Description

Count

Audio packet size in bytes.

IBMDStreamingAudioPacket::GetBytes method
The GetBytes method returns a pointer to the data buffer of the audio packet.
SyntaxHRESULT

GetBytes (void* buffer);Parameters
Name

Direction

Description

bufferout

Pointer to audio packet data buffer – only valid while object
remains valid.

Return Values
Value

Description

S_OK

Success

E_POINTER

The parameter is invalid.

Section 2 — DeckLink API

209

2.6.9.4

IBMDStreamingAudioPacket::GetPlayTime method
The GetPlayTime method returns the time at which to playback the audio contained in the audio packet.
The play time is in units of the requested time scale.
SyntaxHRESULT

GetPlayTime (uint64_t requestedTimeScale, uint64_t* playTime);Parameters
Name

Direction

Description

requestedTimeScaleinTime scale for the displayTime

playTime

outTime at which to play the audio

Return Values

2.6.10Value

Description

S_OK

Success

E_POINTER

The parameter is invalid.

IBMDStreamingMPEG2TSPacket Interface
The IBMDStreamingMPEG2TSPacket object interface represents an MPEG-2 transport stream packet as
defined by ISO/IEC 13818-1.
Objects with an IBMDStreamingMPEG2TSPacket object interface are passed to the
IBMDStreamingH264InputCallback::MPEG2TSPacketArrived callback.
The MPEG-2 transport stream packet can contain compressed audio or video together with metadata for decoding andsynchronizing audio and video streams. For some applications it may be more convenient to process transport stream
packets as an alternative to processing NAL video packets and audio packets separately.
Related Interfaces
Interface

Interface ID

Description

IBMDStreaming
H264InputCallback

IID_IBMDStreaming
H264InputCallback

New MPEG-2 transport stream packets are passed to the
IBMDStreamingH264InputCallback::MPEG2TSPacketArrived
callback

Public Member Functions
MethodDescription

GetPayloadSize

Get number of bytes in the MPEG-2 transport stream packet

GetBytes

Get pointer to MPEG-2 transport stream packet

Section 2 — DeckLink API

210

2.6.10.1

IBMDStreamingMPEG2TSPacket::GetPayloadSize method
The GetPayloadSize method returns the number of bytes in the MPEG-2 transport stream packet including the header.
Syntaxlong

GetPayloadSize ();Return Values
Value

Description

Count

The size of the MPEG TS packet in bytes.

2.6.10.2 IBMDStreamingMPEG2TSPacket::GetBytes method
The GetBytes method returns a pointer to the data buffer of the MPEG-2 transport stream packet.
SyntaxHRESULT

GetBytes (void* buffer);Parameters
Name

Direction

Description

bufferout

Pointer to MPEG-2 transport stream packet data buffer only valid while
object remains valid.

Return Values

2.6.11

Value

Description

E_FAIL

FailureS_OK

Success

E_POINTER

The parameter is invalid

IBMDStreamingH264NALParser Interface
The IBMDStreamingH264NALParser object interface is used to retrieve video codec settings from a
NAL packet.
A reference to an IBMDStreamingH264NALParser object interface may be obtained from
CoCreateInstance on platforms with native COM support or from CreateBMDStreamingH264NALParser
on other platforms.
Related Interfaces
Interface

Interface ID

Description

BMDStreamingH264NALPacket

IID_
IBMDStreamingH264NALPacket

The NAL packet to be parsed by a method in the
IBMDStreamingH264NALParser object interface

Public Member Functions
MethodDescription

IsNALSequenceParameterSet

Get the packet’s Sequence Parameter Set setting

IsNALPictureParameterSet

Get the packet’s Picture Parameter Set setting

GetProfileAndLevelFromSPS

Get the packet’s profile and level setting

Section 2 — DeckLink API

211

2.6.11.1

IBMDStreamingH264NALParser::IsNALSequenceParameterSet method
The IsNALSequenceParameterSet method parses the specified NAL packet to determine if theSequence Parameter Set (SPS) decoding parameter has been set in the NAL packet.
SyntaxHRESULTIsNALSequenceParameterSet (IBMDStreamingH264NALPacket* nal);Parameters
Name

Direction

Description

nal

in

The NAL Packet to query for the state of the sequence parameter.

Return Values

2.6.11.2

Value

Description

S_OK

The sequence parameter of the NAL packet is set.

S_FALSEThe sequence parameter of the NAL packet is not set.

IBMDStreamingH264NALParser::IsNALPictureParameterSet method
The IsNALPictureParameterSet method parses the specified NAL packet to determine if the Picture
Parameter Set (PPS) decoding parameter has been set in the NAL packet. This information can be used toconfigure a decoder for decoding the video contained in the NAL packet.
SyntaxHRESULTIsNALPictureParameterSet (IBMDStreamingH264NALPacket* nal);Parameters
Name

Direction

Description

nal

in

The NAL Packet to query for the state of the picture parameter.

Return Values
Value

Description

S_OK

The picture parameter of the NAL packet is set.

S_FALSEThe picture parameter of the NAL packet is not set.

Section 2 — DeckLink API212

2.6.11.3

IBMDStreamingH264NALParser::GetProfileAndLevelFromSPS method
The GetProfileAndLevelFromSPS method parses the specified NAL packet and returns the H.264 profile,level and profile compatibility flags. These values can be used to determine if the video contained in the
NAL packet can be decoded by a certain H.264 decoder.
SyntaxHRESULT

 etProfileAndLevelFromSPS (IBMDStreamingH264NALPacket* nal,G
uint32_t* profileIdc, uint32_t* profileCompatability, uint32_t* levelIdc);

Parameters
Name

Direction

Description

nal

in

The NAL Packet to query for the profile and level.

profileIdc

out

The H.264 profile for this NAL packet.

profileCompatabilityout

The set of profile constraint flags for this NAL packet.

levelIdc

out

The H.264 level for this NAL packet.

Return Values
Value

Description

E_FAIL

FailureS_OK

Success

E_POINTER

One or more parameters are invalid.

Section 2 — DeckLink API

213

Section 3 — Common Data Types
3.1

Basic Types
booleanboolean is represented differently on each platform by using its system type:
Windows

BOOL

macOS

bool

Linux

bool

stringstring are represented differently on each platform, using the most appropriate system type:
Windows

BSTR

macOS

CFStringRef

Linux

const char *int64_t
The 64 bit integer type is represented differently on each platform, using the most appropriate
system type:
Windows

LONGLONG

macOS

int64_tLinux

int64_tuint64_t
The 64 bit unsigned integer type is represented differently on each platform, using the most appropriate
system type:
Windows

ULONGLONG

macOS

uint64_tLinux

uint64_t

uint32_t
The 32 bit unsigned integer type is represented differently on each platform, using the most appropriate
system type:
Windows

unsigned int

macOS

uint32_tLinux

uint32_t

Section 3 — Common Data Types214

int32_t
The 32 bit integer type is represented differently on each platform, using the most appropriate
system type:
Windows

int

macOS

int32_tLinux

int32_tuint16_t
The 16 bit unsigned integer type is represented differently on each platform, using the most appropriate
system type:
Windows

unsigned shortmacOS

uint16_t

Linux

uint16_t

uint8_t
The 8 bit unsigned integer type is represented differently on each platform, using the most appropriate
system type:

3.2

Windows

unsigned charmacOS

uint8_tLinux

uint8_t

Time Representation
The API uses a flexible scheme to represent time values which can maintain accuracy for any video or
audio rate. Time is always represented as a time scale and a time value. The time scale is a unit of ticks
per second specified by the API user. Time values are represented as a number of time units since
playback or capture began. The API user should choose a time scale value appropriate to the type ofvideo or audio stream being handled. Some examples are provided below:
Stream Type

Suggested Time Scale

Frame Time Values

24 fps video

24000

0, 1000, 2000, 3000…

23.98 fps video

24000

0, 1001, 2002, 3003...

BMDTimeScale
BMDTimeScale is a large integer type which specifies the time scale for a time measurement in ticks
per second.
BMDTimeValueBMDTimeValue is a large integer type which represents a time in units of BMDTimeScale.
BMDTimecodeUserBits
BMDTimecodeUserBits is a 32-bit unsigned integer representing timecode user bits.

Section 3 — Common Data Types

215

3.3

Display Modes
BMDDisplayMode enumerates the video modes supported for output and input.

Mode

Width

HeightFramesper Second

Fieldsper Frame

Suggested
Time Scale

Frame
Duration

bmdModeNTSC

720

486

30/1.001

2

30000

1001

bmdModeNTSC2398

720

486

30/1.001*

2

24000*

1001

bmdModeNTSCp

720

486

60/1.001

1

60000

1001

bmdModePAL

720

576

25

2

25000

1000

bmdModePALp

720

576

50

1

50000

1000

bmdModeHD720p50

1280

720

50

1

50000

1000

bmdModeHD720p5994

1280

720

60/1.001

1

60000

1001

bmdModeHD720p60

1280

720

60

1

60000

1000

bmdModeHD1080p2398

1920

1080

24/1.001

1

24000

1001

bmdModeHD1080p24

1920

1080

24

1

24000

1000

bmdModeHD1080p25

1920

1080

25

1

25000

1000

bmdModeHD1080p2997

1920

1080

30/1.001

1

30000

1001

bmdModeHD1080p30

1920

1080

30

1

30000

1000

bmdModeHD1080p4795

1920

1080

48/1.001

1

48000

1001

bmdModeHD1080p48

1920

1080

48

1

48000

1000

bmdModeHD1080i50

1920

1080

25

2

25000

1000

bmdModeHD1080i5994

1920

1080

30/1.001

2

30000

1001

bmdModeHD1080i6000

1920

1080

30

2

30000

1000

bmdModeHD1080p50

1920

1080

50

1

50000

1000

bmdModeHD1080p5994

1920

1080

60/1.001

1

60000

1001

bmdModeHD1080p6000

1920

1080

60

1

60000

1000

bmdModeHD1080p9590

1920

1080

96/1.001

1

96000

1001

bmdModeHD1080p96

1920

1080

96

1

96000

1000

bmdModeHD1080p100

1920

1080

100

1

1000001000

bmdModeHD1080p11988

1920

1080

120/1.001

11200001001

bmdModeHD1080p120

1920

1080

120

1

1200001000

bmdMode2k2398

2048

1556

24/1.001

1

24000

1001

bmdMode2k24

2048

1556

24

1

24000

1000

bmdMode2k25

2048

1556

25

1

25000

1000

bmdMode2kDCI2398

2048

1080

24/1.001

1

24000

1001

bmdMode2kDCI24

2048

1080

24

1

24000

1000

bmdMode2kDCI25

2048

1080

25

1

25000

1000

Section 3 — Common Data Types

216

Mode

Width

HeightFramesper Second

Fieldsper Frame

Suggested
Time Scale

Frame
Duration

bmdMode2kDCI2997

2048

1080

30/1.001

1

30000

1001

bmdMode2kDCI30

2048

1080

30

1

30000

1000

bmdMode2kDCI4795

2048

1080

48/1.001

1

48000

1001

bmdMode2kDCI48

2048

1080

48

1

48000

1000

bmdMode2kDCI50

2048

1080

50

1

50000

1000

bmdMode2kDCI5994

2048

1080

60/1.001

1

60000

1001

bmdMode2kDCI60

2048

1080

60

1

60000

1000

bmdMode2kDCI9590

2048

1080

96/1.001

1

96000

1001

bmdMode2kDCI96

2048

1080

96

1

96000

1000

bmdMode2kDCI100

2048

1080

100

1

1000001000

bmdMode2kDCI11988

2048

1080

120/1.001

11200001001

bmdMode2kDCI120

2048

1080

120

1

1200001000

bmdMode4K2160p2398

3840

2160

24/1.001

1

24000

1001

bmdMode4K2160p24

3840

2160

24

1

24000

1000

bmdMode4K2160p25

3840

2160

25

1

25000

1000

bmdMode4K2160p2997

3840

2160

30/1.001

1

30000

1001

bmdMode4K2160p30

3840

2160

30

1

30000

1000

bmdMode4K2160p4795

3840

2160

48/1.001

1

48000

1001

bmdMode4K2160p48

3840

2160

48

1

48000

1000

bmdMode4K2160p50

3840

2160

50

1

50000

1000

bmdMode4K2160p5994

3840

2160

60/1.001

1

60000

1001

bmdMode4K2160p60

3840

2160

60

1

60000

1000

bmdMode4K2160p9590

3840

2160

96/1.001

1

96000

1001

bmdMode4K2160p96

3840

2160

96

1

96000

1000

bmdMode4K2160p100

3840

2160

100

1

1000001000

bmdMode4K2160p11988

3840

2160

120/1.001

11200001001

bmdMode4K2160p120

3840

2160

120

1

1200001000

bmdMode4kDCI2398

4096

2160

24/1.001

1

24000

1001

bmdMode4kDCI24

4096

2160

24

1

24000

1000

bmdMode4kDCI25

4096

2160

25

1

25000

1000

bmdMode4kDCI2997

4096

2160

30/1.001

1

30000

1000

bmdMode4kDCI30

4096

2160

30

1

30000

1000

bmdMode4kDCI4795

4096

2160

48/1.001

1

48000

1001

bmdMode4kDCI48

4096

2160

48

1

48000

1000

Section 3 — Common Data Types

217

Mode

Width

HeightFramesper Second

Fieldsper Frame

Suggested
Time Scale

Frame
Duration

bmdMode4kDCI50

4096

2160

50

1

50000

1000

bmdMode4kDCI5994

4096

2160

60/1.001

1

60000

1001

bmdMode4kDCI9590

4096

2160

96/1.001

1

96000

1001

bmdMode4kDCI96

4096

2160

96

1

96000

1000

bmdMode4kDCI100

4096

2160

100

1

1000001000

bmdMode4kDCI11988

4096

2160

120/1.001

11200001001

bmdMode4kDCI120

4096

2160

120

1

1200001000

bmdMode8K4320p2398

7680

4320

24/1.001

1

24000

1001

bmdMode8K4320p24

7680

4320

24

1

24000

1000

bmdMode8K4320p25

7680

4320

25

1

25000

1000

bmdMode8K4320p2997

7680

4320

30/1.001

1

30000

1001

bmdMode8K4320p30

7680

4320

30

1

30000

1000

bmdMode8K4320p4795

7680

4320

48/1.001

1

48000

1001

bmdMode8K4320p48

7680

4320

48

1

48000

1000

bmdMode8K4320p50

7680

4320

50

1

50000

1000

bmdMode8K4320p5994

7680

4320

60/1.001

1

60000

1001

bmdMode8K4320p60

7680

4320

60

1

60000

1000

bmdMode8kDCI2398

8192

4320

24/1.001

1

24000

1001

bmdMode8kDCI24

8192

4320

24

1

24000

1000

bmdMode8kDCI25

8192

4320

25

1

25000

1000

bmdMode8kDCI2997

8192

4320

30/1.001

1

30000

1001

bmdMode8kDCI30

8192

4320

30

1

30000

1000

bmdMode8kDCI4795

8192

4320

48/1.001

1

48000

1001

bmdMode8kDCI48

8192

4320

48

1

48000

1000

bmdMode8kDCI50

8192

4320

50

1

50000

1000

bmdMode8kDCI5994

8192

4320

60/1.001

1

60000

1001

bmdMode8kDCI60

8192

4320

60

1

60000

1000

bmdMode640x480p60

640

480

60

1

60000

1000

bmdMode800x600p60

800

600

60

1

60000

1000

bmdMode1440x900p50

1440

900

50

1

50000

1000

bmdMode1440x900p60

1440

900

60

1

60000

1000

bmdMode1440x1080p50

1440

1080

50

1

50000

1000

bmdMode1440x1080p60

1440

1080

60

1

60000

1000

bmdMode1600x1200p50

1600

1200

50

1

50000

1000

Section 3 — Common Data Types

218

Mode

Width

HeightFramesper Second

Fieldsper Frame

Suggested
Time Scale

Frame
Duration

bmdMode1600x1200p60

1600

1200

60

1

60000

1000

bmdMode1920x1200p50

1920

1200

50

1

50000

1000

bmdMode1920x1200p60

1920

1200

60

1

60000

1000

bmdMode1920x1440p50

1920

1440

50

1

50000

1000

bmdMode1920x1440p60

1920

1440

60

1

60000

1000

bmdMode2560x1440p50

2560

1440

50

1

50000

1000

bmdMode2560x1440p60

2560

1440

60

1

60000

1000

bmdMode2560x1600p50

2560

1600

50

1

50000

1000

bmdMode2560x1600p60

2560

1600

60

1

60000

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 modes.

NOTE VANC data widths are the same as the display mode width, with the exception of UHD
4K/8K modes (1080 pixels) and DCI 4K/8K modes (2048 pixels).

Section 3 — Common Data Types

219

3.4

Pixel Formats
BMDPixelFormat enumerates the pixel formats supported for output and input.

bmdFormat8BitYUV : ‘2vuy’ 4:2:2 Representation
Four 8-bit unsigned components (CCIR 601) are packed into one 32-bit little-endian word.
Word
Decreasing Address Order

7

6

5

Byte 3

Byte 2Byte 1

B yte 0

Y’ 1

Cr 0

Y’ 0

Cb 0

4

3

2

1

0

7

6

5

4

int framesize==(Width * 16 / 8) * Heightrowbytes * Height

3

2

1

0

7

6

5

4

3

2

1

0

7

6

5

4

3

2

1

0

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.

bmdFormat10BitYUV : ‘v210’ 4:2:2 Representation
Twelve 10-bit unsigned components are packed into four 32-bit little-endian words.
Word 0Decreasing Address Order
Byte 3
X

X

Byte 2Byte 1

Cr 0
9

8

7

6

5

4

Byte 0

Y’ 0
3

2

1

0

9

8

7

6

5

4

Cb 0
3

2

1

0

9

8

7

6

5

4

3

2

1

0

3

2

1

0

3

2

1

0

Word 1
Decreasing Address Order
Byte 3
X

X

Byte 2Byte 1

Y’ 2
9

8

7

6

5

4

Byte 0

Cb 2
3

2

1

0

9

8

7

6

5

4

Y’ 1
3

2

1

0

9

8

7

6

5

4

Word 2
Decreasing Address Order
Byte 3
X

X

Byte 2Byte 1

Cb 4
9

8

7

6

5

4

Byte 0

Y’3
3

2

1

0

9

8

7

6

5

4

Cr 2
3

2

1

0

9

8

7

6

5

4

Section 3 — Common Data Types

220

Word 3
Decreasing Address Order
Byte 3
X

X

Byte 2Byte 1

Y’ 5
9

5

4

Byte 0

Cr 4

8

7

6

3

2

1

0

9

8

7

int framesize==((Width + 47) / 48) * 128 * Heightrowbytes * Height

6

5

4

Y’ 4
3

2

1

0

9

8

7

6

5

4

3

2

1

0

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

bmdFormat10BitYUVA: ‘Ay10’ 4:2:2 raw
Six 10-bit unsigned components are packed into two 32-bit big-endian words. The alpha channel is valid
and full range.
int rowBytes =int frameSize =((width + 63) / 64) * 256
rowBytes * height

In this format each line of video must be aligned to 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 andmultiplied by 256.
For the frame size calculation, the row bytes are simply multiplied by the number of rows in the frame.
On all connectors using YCbCr, or HDMI, playback without keying enabled will drop the alpha and capture
will set the alpha to the peak nominal value.
Word 0Decreasing Address Order
Byte 3

Byte 2

Y’0
7

6

5

4

3

Byte 1

Cb0
2

1

0

5

4

3

2

Y’0
1

0

9

8

A0
3

2

Byte 0
Cb0

1

0

9

8

7

6

X

X

X

X

A0
9

8

7

6

5

4

5

4

Word 1
Decreasing Address Order
Byte 3

Byte 2

Y'1
7

6

5

4

3

Byte 1

Cr0
2

1

0

5

4

3

2

Y'1
1

0

9

8

A0
3

2

Byte 0
Cr0

1

0

9

8

7

6

X

X

X

X

A0
9

8

7

6

Section 3 — Common Data Types

221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

7

6

5

Byte 3

Byte 2Byte 1

Byte 0

B

G

R

A

4

3

2

1

0

7

6

5

4

3

int framesize==(Width * 32 / 8) * Heightrowbytes * Height

2

1

0

7

6

5

4

3

2

1

0

7

6

5

4

3

2

1

0

In this format, each pixel fits into 32 bits or 4 bytes. For the row bytes calculation the image width ismultiplied 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.
On all connectors using YCbCr, or HDMI, playback without keying enabled will drop the alpha and capture
will set the alpha to the peak nominal value.

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

7

6

5

Byte 3

Byte 2Byte 1

Byte 0

X

R

G

B

4

3

2

1

0

7

6

5

4

int framesize==(Width * 32 / 8) * Heightrowbytes * Height

3

2

1

0

7

6

5

4

3

2

1

0

7

6

5

4

3

2

1

0

In this format, each pixel fits into 32 bits or 4 bytes. For the row bytes calculation, the image width ismultiplied 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.
On all connectors using YCbCr, or HDMI, playback without keying enabled will drop the alpha and capture
will set the alpha to the peak nominal value.

Section 3 — Common Data Types222

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

Byte 2

B Lo
7

6

5

Byte 1

G Lo
1

0

5

4

3

B Hi

4

3

2

2

1

0

9

8

int framesize==((Width + 63) / 64) * 256 * Heightrowbytes * Height

R Lo
3

2

1

Byte 0
G Hi

0

9

8

7

X

X

x

x

6

R Hi
9

8

7

6

5

4

In 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 andmultiplied by 256.
For the frame size calculation, the row bytes are simply multiplied by the number of rows in the frame.

bmdFormat12BitRGB : ‘R12B’
Big-endian RGB 12-bit per component with full range (0-4095). Packed as 12-bit per component.
This 12-bit pixel format is compatible with SMPTE 268M Digital Moving-Picture Exchange version 1, Annex
C, Method C4 packing.
int framesize==((Width * 36) / 8) * Heightrowbytes * Height

In this format, 8 pixels fit into 36 bytes.
Word 0Decreasing Address Order
Byte 3

Byte 2

R0
7

6

5

4

3

G0
2

1

0

3

2

1

R0
0 11 10 9

8 11 10 9

Byte 1

Byte 0

G0

B0

8

7

6

5

4

7

6

5

4

3

2

1

0

0 11 10 98

Word 1
Decreasing Address Order
Byte 3R1
3

2

Byte 2Byte 1

R1

G1

B0
1

0 11 10 9

8 11 10 9

8

7

6

5

4

7

6

5

4

Byte 0
B1

3

2

1

0

3

2

G1
1

Word 2
Decreasing Address Order

11 10 9Byte 3

Byte 2

B1

R2

8

7

6

5

4

7

6

5

4

3

Byte 1
G2
2

1

0

3

2

1

Byte 0R2

0 11 10 9G2
8 11 10 9

8

7

6

5

Section 3 — Common Data Types

4223

Word 3
Decreasing Address Order
Byte 3

Byte 2

B2
7

6

5

4

3

R3
2

1

0

3

2

B2
1

0 11 10 9

8 11 10 9

Byte 1

Byte 0

R3

G3

8

7

6

5

4

7

6

5

4

3

2

1

0

0 11 10 98

Word 4
Decreasing Address Order
Byte 3
B3
3

2

G3
1

0 11 10 9

8 11 10 9

Byte 2Byte 1

B3

R4

8

7

6

5

4

7

6

5

4

3

Byte 0
G4
2

1

0

3

2

1

R4

Word 5Decreasing Address Order
Byte 3

Byte 2Byte 1G4
11 10 9

8

7

B4
6

5

4

7

6

5

4

3

Byte 0

R5
2

1

0

3

2

B4
1

R5

0 11 10 9

8 11 10 9

8

7

6

5

4

2

1

0

0 11 10 98

Word 6
Decreasing Address Order
Byte 3

Byte 2

G5
7

6

5

4

3

B5
2

1

0

3

2

G5
1

0 11 10 9

8 11 10 9

Byte 1

Byte 0

B5

R6

8

7

6

5

4

7

6

5

4

3

Word 7
Decreasing Address Order
Byte 3
G6
3

2

1

R6
0 11 10 9

8 11 10 9

Byte 2Byte 1

G6

B6

8

7

6

5

4

7

6

5

4

3

Byte 0
R7
2

1

0

3

2

B6
1

Word 8Decreasing Address Order

11 10 9Byte 3

Byte 2

R7

G7

8

7

6

5

4

7

6

5

4

3

Byte 1
B7
2

1

0

3

2

Byte 0G7

1

0 11 10 9

B7
8 11 10 9

8

7

6

5

Section 3 — Common Data Types

4

224

bmdFormat12BitRGBLE : ‘R12L’
Little-endian RGB 12-bit per component with full range (0-4095). Packed as 12-bit per component.
This 12-bit pixel format is compatible with SMPTE 268M Digital Moving-Picture Exchange version 1, Annex
C, Method C4 packing.
int framesize==((Width * 36) / 8) * Heightrowbytes * Height

In this format, 8 pixels fit into 36 bytes.
Word 0Decreasing Address Order

7

6

5

Byte 3

Byte 2

B0

G0

4

3

2

1

0 11 10 987

Byte 1

Byte 0

G0
6

5

4

3

2

1

R0

R0

0 11 10 9

8

7

6

5

4

3

2

1

0

0 11 10 98

Word 1
Decreasing Address Order
Byte 3

Byte 2B1
3

2

Byte 1G1
1

Byte 0G1

0 11 10 9

8

7

6

5

4

R1
3

2

1

0 11 10 9

8

R1
7

6

5

4

3

2

B0
1

Word 2
Decreasing Address Order
Byte 3

Byte 2G2
11 10 9

8

7

G2
6

5

4

3

2

1

Byte 1

Byte 0R2

B1

R2
0 11 10 9

8

7

6

5

4

3

2

1

0 11 10 9

8

7

6

5

4

2

1

0

0 11 10 98

Word 3
Decreasing Address Order

7

6

5

Byte 3

Byte 2

G3

R3

4

3

2

1

0 11 10 987

Byte 1
R3
6

5

4

3

2

Byte 0B2

1

0 11 10 9

B2
8

7

6

5

4

3

Word 4
Decreasing Address Order
Byte 3
G4
3

2

R4
1

0 11 10 9

8

7

6

5

Byte 2Byte 1

R4

B3

4

3

2

1

0 11 10 987

Byte 0
B3
6

5

4

3

2

G3
1

Section 3 — Common Data Types

225

Word 5Decreasing Address Order
Byte 3

Byte 2R5
11 10 9

8

R5

7

6

5

4

3

2

B4
1

0 11 10 9

8

7

6

5

Byte 1

Byte 0

B4

G4

4

3

2

1

0 11 10 9

8

7

6

5

4

2

1

0

0 11 10 98

Word 6
Decreasing Address Order

7

6

5

Byte 3

Byte 2

R6

B5

4

3

2

1

0 11 10 98

Byte 1
B5

7

6

5

4

3

2

Byte 0G5

1

0 11 10 9

G5
8

7

6

5

4

3

Word 7
Decreasing Address Order
Byte 3
R7
3

2

B6
1

0 11 10 9

8

7

6

5

Byte 2Byte 1

B6

G6

4

3

2

1

0 11 10 987

Byte 0
G6
6

5

4

3

2

R6

1

Word 8Decreasing Address Order
Byte 3

Byte 2B7
11 10 9

8

B7

7

6

5

4

3

2

G7
1

0 11 10 9

8

7

6

5

Byte 1

Byte 0

G7

R7

4

3

2

1

0 11 10 9

8

7

6

5

4

bmdFormat10BitRGBXLE : ‘R10l’ 4:4:4 raw
Three 10-bit unsigned components are packed into one 32-bit little-endian word.
Word
Decreasing Address Order
Byte 3

Byte 2

R
9

8

7

R
3

2

1

Byte 1

G
0 9

8

7

Byte 0

G

6

5

4

6

5

int framesize==((Width + 63) / 64) * 256 * Heightrowbytes * Height

4

3

2

B
1

0 9

8

B
7

6

5

4

3

X X
2

1

0

x

x

In 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 andmultiplied by 256.
For the frame size calculation, the row bytes are simply multiplied by the number of rows in the frame.

Section 3 — Common Data Types

226

bmdFormat10BitRGBX : ‘R10b’ 4:4:4 raw
Three 10-bit unsigned components are packed into one 32-bit big-endian word.
Word
Decreasing Address Order
Byte 3

Byte 2

B
5

4

3

X X
x

x

Byte 1

G
3

2

B
1

0 9

8

R

2

1

0

7

int framesize==((Width + 63) / 64) * 256 * Heightrowbytes * Height6

1

Byte 0

G
0 9

8

7

R
6

5

4

9

8

7

6

5

4

3

2

In 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 andmultiplied by 256.
For the frame size calculation, the row bytes are simply multiplied by the number of rows in the frame.
— bmdFormatH265 : ‘hev1’
This pixel format represents compressed H.265 encoded video data.
— This pixel format is compatible with ITU-T H.265 High Efficiency Video Coding.
— bmdFormatDNxHR : ‘AVdh’
This pixel format represents compressed DNxHR encoded video data.
— bmdFormatUnspecified
This represents any pixel format for the purpose of checking display mode support with the
IDeckLinkInput::DoesSupportVideoMode and IDeckLinkOutput::DoesSupportVideoMode methods.

3.5

Field Dominance
BMDFieldDominance enumerates settings applicable to video fields.
— bmdUnknownFieldDominanceIndeterminate field dominance.
— bmdLowerFieldFirstThe first frame starts with the lower field (the second-from-the-top scan line).
— bmdUpperFieldFirstThe first frame starts with the upper field (the top scan line).
— bmdProgressiveFrame
A complete frame containing all scan lines.
— bmdProgressiveSegmentedFrame
A progressive frame encoded as a PsF (See IDeckLinkDisplayMode::GetFieldDominancefor details)

Section 3 — Common Data Types

227

3.6

Frame Flags
BMDFrameFlags enumerates a set of flags applicable to a video frame.
— bmdFrameFlagDefault
No other flags applicable.
— bmdFrameFlagFlipVertical
Frame should be flipped vertically on output— bmdFrameFlagMonitorOutOnly
Output this frame on Monitor Output only and black/silence on all other outputs. Only available when
BMDDeckLinkHasMonitorOut attribute is True.
— bmdFrameContainsHDRMetadata
Frame contains HDR metadata (See IDeckLinkVideoFrameMetadataExtensions)— bmdFrameContainsDolbyVisionMetadata
Frame contains Dolby Vision metadata (see IDeckLinkVideoFrameMetadataExtensions)— bmdFrameCapturedAsPsF
Frame captured as PsF— bmdFrameHasNoInputSource
No input source was detected – frame is invalid

3.7

Video Input Flags
BMDVideoInputFlags enumerates a set of flags applicable to video input.
— bmdVideoInputFlagDefault
No other flags applicable— bmdVideoInputEnableFormatDetection
Enable video input mode detection.
(See IDeckLinkInputCallback::VideoInputFormatChanged for details)— bmdVideoInputDualStream3D
Set the DeckLink device to capture the 3D mode version of the selected BMDDisplayMode
display mode.
— bmdVideoInputSynchronizeToCaptureGroup
Enable grouping with other DeckLInk devices to synchonize the capture start and stop

3.8

Video Output Flags
BMDVideoOutputFlags enumerates flags which control the output of video data.
— bmdVideoOutputFlagDefault
No flags applicable.
— bmdVideoOutputRP188
Output RP188 timecode. If supplied see: IDeckLinkMutableVideoFrame::SetTimecode— bmdVideoOutputVANC
Output VANC data. If supplied see: IDeckLinkMutableVideoFrame::SetAncillaryData— bmdVideoOutputVITC
Output VITC timecode data. If supplied see: IDeckLinkMutableVideoFrame::SetTimecode— bmdVideoOutputDualStream3D
Set the DeckLink device to output the 3D version of the selected
BMDDisplayMode display mode.
— bmdVideoOutputSynchronizeToPlaybackGroup
Enable grouping with other DeckLInk devices to synchonize the playback start and stop.
— bmdVideoOutputDolbyVision
Enable Dolby Vision.

Section 3 — Common Data Types

228

3.9

Output Frame Completion Results Flags
BMDOutputFrameCompletionResult enumerates the possible frame output completion statuses.
— bmdOutputFrameCompleted
Frame was displayed normally— bmdOutputFrameDisplayedLate
Frame was displayed late
— bmdOutputFrameDropped
Frame was dropped— bmdOutputFrameFlushed
Frame was flushed
Frames are “flushed” when they have been scheduled but are no longer needed due to an action initiatedby the API user e.g. a speed or direction change. If frame scheduling falls behind frame output, thehardware 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”.

3.10

Frame Preview Format
BMD3DPreviewFormat enumerates the dual preview formats available for the DeckLink screen preview.
The OpenGL based preview format can be set using
IDeckLinkGLScreenPreviewHelper::Set3DPreviewFormat.
The DirectX based preview format can be set using
IDeckLinkDX9ScreenPreviewHelper::Set3DPreviewFormat.
— bmd3DPreviewFormatDefault
Preview frames in the default top-bottom format.
— bmd3DPreviewFormatLeftOnly
Preview the left eye frame only.
— bmd3DPreviewFormatRightOnly
Preview the right eye frame only.
— bmd3DPreviewFormatSideBySide
Preview the frames frame in side by side format— bmd3DPreviewFormatTopBottom
Preview the frames in top-bottom format.

3.11

Video IO Support
BMDVideoIOSupport enumerates the capture and playback capabilities of a device.
— bmdDeviceSupportsCapture
The DeckLink device supports capture operations.
— bmdDeviceSupportsPlayback
The DeckLink device supports playback operation.

Section 3 — Common Data Types

229

3.12

Video Connection Modes
BMDVideoConnection enumerates the possible video connection interfaces.
— bmdVideoConnectionUnspecified
Unspecified video connection, for purpose of checking video mode support with
IDeckLinkInput::DoesSupportVideoMode and IDeckLinkOutput::DoesSupportVideoMode methods.
— bmdVideoConnectionSDI
SDI video connection— bmdVideoConnectionHDMI
HDMI video connection— bmdVideoConnectionOpticalSDI
Optical SDI connection— bmdVideoConnectionComponent
Component video connection— bmdVideoConnectionComposite
Composite video connection— bmdVideoConnectionSVideo
S-Video connection— bmdVideoConnectionEthernet
Ethernet connection— bmdVideoConnectionOpticalEthernet
Optical Ethernet connection

3.13

Link Configuration
BMDLinkConfiguration enumerates the SDI video link configuration on a DeckLink device.
— bmdLinkConfigurationSingleLink
A single link video connection. A single video stream uses one connector.
— bmdLinkConfigurationDualLink
A dual-link video connection. A single video stream uses two connectors.
— bmdLinkConfigurationQuadLink
A quad-link video connection. A single video stream uses four connectors

3.14

Audio Sample Rates
BMDAudioSampleRate enumerates the possible audio sample rates.
— bmdAudioSampleRate48kHz
48 kHz sample rate

3.15

Audio Sample Types
BMDAudioSampleType enumerates the possible audio sample types.
— bmdAudioSampleType16bitInteger
16 bit audio sample— bmdAudioSampleType32bitInteger
32 bit audio sample

Section 3 — Common Data Types

230

3.16

DeckLink Information ID
BMDDeckLinkAPIInformationID enumerates a set of information details which may be queried (seeIDeckLinkAPIInformation Interface for details).
Name

Type

Description

BMDDeckLinkAPIVersion

String

The user viewable API version number.
This allocated string must be freed by the caller when no longer required.

BMDDeckLinkAPIVersion

Int

The API version number. Format:

Word
Decreasing Adress Order
Byte 4

Byte 3Major Version

3.17

Byte 2

Minor Version

Byte 1

Sub Version

Extra

DeckLink Attribute ID
BMDDeckLinkAttributeID enumerates a set of attributes of a DeckLink device which may be queried (seeIDeckLinkProfileAttributes Interface for details).
Name

Type

Description

BMDDeckLinkProfileID

Int

The Profile ID for the current IDeckLinkProfileAttributes.
See BMDProfileID for more information

BMDDeckLinkSupportsInternalKeying

Flag

True if internal keying is supported on this device.

BMDDeckLinkSupportsExternalKeying

Flag

True if external keying is supported on this device.
The operating system name of the RS422 serial porton this device.

BMDDeckLinkSerialPortDeviceName

String

BMDDeckLinkMaximumAudioChannels

Int

The maximum number of audio channels embedded on
digital connections supported by this device.

BMDDeckLinkMaximumHDMIAudioChannels

Int

The maximum number of audio channels embedded on
HDMI supported by this device.

BMDDeckLinkMaximumAnalog
AudioInputChannels

Int

The maximum number of input analog audio channels
supported by this device.

BMDDeckLinkMaximumAnalog
AudioOutputChannels

Int

The maximum number of output analog audio channels
supported by this device.

BMDDeckLinkSupportsInputFormatDetection

Flag

True if input format detection is supported on this device.

BMDDeckLinkHasReferenceInput

Flag

True if the DeckLink device has a genlock reference source
input connector.

BMDDeckLinkHasSerialPort

Flag

True if device has a serial port.

This allocated string must be freed by the caller when
no longer required.

Some DeckLink hardware devices contain multiple
independent sub-devices.
BMDDeckLinkNumberOfSubDevices

BMDDeckLinkSubDeviceIndex

Int

Int

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, startingfrom zero.

Section 3 — Common Data Types

231

Name

BMDDeckLinkVideoOutputConnections

Type

Int

Description
The video output connections supported by the hardware(see BMDVideoConnection for more details).
Multiple video output connections can be active
simultaneously.
The audio output connections supported by the hardware(see BMDAudioConnection for more details).

BMDDeckLinkAudioOutputConnections

Int

Multiple audio output connections can be active
simultaneously. Devices with one or more types of analog
connection will have the bmdAudioConnectionAnalog flag
set.
Devices with individually selectable XLR/RCA connectors
will additionally have the bmdAudioConnectionAnalogXLR
and bmdAudioConnectionAnalogRCA flags set.

BMDDeckLinkVideoInputConnections

Int

The video input connections supported by the hardware(see BMDVideoConnection for more details).

BMDDeckLinkAudioInputConnections

Int

The audio input connections supported by the hardware(see BMDAudioConnection for more details).

BMDDeckLinkHasAnalogVideoOutputGain

Flag

True if analog video output gain adjustment is supported on
this device.

BMDDeckLinkCanOnlyAdjustOverallVideo
OutputGain

Flag

True if only the overall video output gain can be adjusted.
In this case, only the luma gain can be accessed with the
IDeckLinkConfiguration interface, and it controls all three
gains (luma, chroma blue and chroma red).

BMDDeckLinkHasVideoInputAntiAliasingFilter

Flag

True if there is an antialising filter on the analog video inputof this device.

BMDDeckLinkHasBypass

Flag

True if this device has loop-through bypass function.

BMDDeckLinkVideoInputGainMinimum

Float

The minimum video input gain in dB for this device.

BMDDeckLinkVideoInputGainMaximum

Float

The maximum video input gain in dB for this device.

BMDDeckLinkVideoOutputGainMinimum

Float

The minimum video output gain in dB for this device.

BMDDeckLinkVideoOutputGainMaximum

Float

The maximum video output gain in dB for this device.

BMDDeckLinkVideoIOSupport

Int

The capture and/or playback capability of the device.
(See BMDVideoIOSupport for more information)

BMDDeckLinkSupportsClockTimingAdjustment

Flag

True if this device supports clock timing adjustment(see bmdDeckLinkConfigClockTimingAdjustment).

BMDDeckLinkPersistentIDInt

A device specific 32 bit unique identifier.

BMDDeckLinkDeviceGroupIDInt

A 32 bit identifier used to group sub-devices belonging to
the same DeckLink hardware device. Supported if the subdevice supports BMDDeckLinkPersistentIDInt

An identifier for DeckLink devices. This feature is supported
on a given device if S_OK is returned. The ID will persist
across reboots assuming that devices are not disconnectedor moved to a different slot.

BMDDeckLinkSupportsFullFrame
ReferenceInputTimingOffset

Flag

True if the DeckLink device supports genlock offset
adjustment wider than +/511 pixels(see bmdDeckLinkConfigReferenceInputTimingOffset
for more information).

BMDDeckLinkSupportsSMPTELevelAOutput

Flag

True if SMPTE Level A output is supported on this device.

BMDDeckLinkSupportsDualLinkSDI

Flag

True if SDI dual-link is supported on this device.

BMDDeckLinkTopologicalID

Section 3 — Common Data Types

232

Name

Type

Description

BMDDeckLinkSupportsQuadLinkSDI

Flag

True if SDI quad-link is supported on this device.

BMDDeckLinkSupportsIdleOutput

Flag

True if this device supports idle output. (seeBMDIdleVideoOutputOperation for idle output options).

BMDDeckLinkDeckControlConnections

Int

The deck control connections supported by the hardware(see BMDDeckControlConnection for more information).

BMDDeckLinkMicrophoneInputGainMinimum

Float

The minimum microphone input gain in dB for this device.

BMDDeckLinkMicrophoneInputGainMaximum

Float

The maximum microphone input gain in dB for this device.

BMDDeckLinkDeviceInterface

Int

The active device interface(see BMDDeviceInterface for more information)

BMDDeckLinkHasLTCTimecodeInput

Flag

True if this device has a dedicated LTC input.

BMDDeckLinkVendorName

StringHardware vendor name. Returned as a static string whichmust not be freed by the caller.

BMDDeckLinkDisplayName

String

The device’s display name.
See IDeckLink::GetDisplayName.

BMDDeckLinkModeName

StringHardware Model Name. See IDeckLink::GetModelName.

BMDDeckLinkSupportsHDRMetadata

Flag

True if the device supports transport of HDR metadata.

BMDDeckLinkAudioInputRCAChannelCountInt

Number of input audio RCA channels supported bythis device.

BMDDeckLinkAudioInputXLRChannelCountInt

Number of input audio XLR channels supported bythis device.

BMDDeckLinkAudioOutputRCAChannelCountInt

Number of output audio RCA channels supported bythis device.

BMDDeckLinkAudioOutputXLRChannelCountInt

Number of output audio XLR channels supported bythis device.

BMDDeckLinkDeviceHandle

StringString representing an unique identifier for the device.
The format of the string is“RevisionID:PersistentID:TopologicalID”.

BMDDeckLinkSupportsColorspaceMetadata

Flag

True if the device supports transport of Colorspace
metadata. See bmdDeckLinkFrameMetadataColorspaceand BMDColorspace for more information.

BMDDeckLinkDuplex

Int

The duplex mode for the corresponding profile.
See BMDDuplexMode for more information

BMDDeckLinkSupportsHighFrameRateTimecode

Flag

True if High Frame Rate Timecode (HFRTC) is supportedby the device.

BMDDeckLinkSupports
SynchronizeToCaptureGroup

Flag

True if the device can be grouped with other input devices
for synchronized capture.

BMDDeckLinkSupports
SynchronizeToPlaybackGroup

Flag

True if the device can be grouped with other output devices
for synchronized playback.

BMDDeckLinkSupportsHDMITimecode

Flag

True if HDMI LTC timecode is supported by the device.

Flag

True if the device supports VANC only when the active
picture is also 10-bit YUV.

BMDDeckLinkVANCRequires10BitYUVVideoFrames

See BMDAncillaryPacketFormat for more information.
BMDDeckLinkMinimumPrerollFrames

Int

The minimum number of preroll video frames required by
the device for scheduled playback

BMDDeckLinkSupportedDynamicRange

Int

The high dynamic range transfer functions supported bythis device. See BMDDynamicRange for more information.

BMDDeckLinkSupportsAutoSwitchingPPsFOnInput

Flag

True if the DeckLink device supports PsF mode detection
on capture.

Section 3 — Common Data Types

233

3.18

Name

Type

Description

BMDDeckLinkEthernetMACAddress

stringFor devices with Ethernet, the local MAC address.

BMDDeckLinkHasMonitorOut

Flag

True if the device has Monitor Out capability.

BMDDeckLinkMezzanineType

Int

The mezzanine board currently attached to this device.
See BMDMezzanineType for more information.

DeckLink Configuration ID
BMDDeckLinkConfigurationID enumerates the set of configuration settings of a DeckLink device which
may be queried or set (see IDeckLinkConfiguration Interface for details).
Name

Type

Description

bmdDeckLinkConfigOutput1080pAsPsF

Flag

If set, output 1080 or 2K progressive modes as PsF.

bmdDeckLinkConfigCapture1080pAsPsF

Flag

If set, capture 1080 or 2K progressive modes as PsF.

bmdDeckLinkConfigHDMI3DPackingFormat

Int(64)

The 3D packing format setting.
See BMDVideo3DPackingFormat for more details.

bmdDeckLinkConfigAnalogAudioConsumerLevels

Flag

If set true the analog audio levels are set to maximum
gain on audio input and maximum attenuation on audio
output. If set false the selected analog input and output
gain levels are used.

bmdDeckLinkConfigFieldFlickerRemoval

Flag

Sets field flicker removal when paused functionality.
True if enabled.

bmdDeckLinkConfigHD1080p24To
HD1080i5994Conversion

Flag

True if HD 1080p24 to HD 1080i5994 conversion isenabled.

bmdDeckLinkConfig444SDIVideoOutput

Flag

True if 444 video output is enabled.

bmdDeckLinkConfigBlackVideoOutputDuringCapture

Flag

True if black output during capture is enabled. Thisfeature is only supported on legacy DeckLink devices.

bmdDeckLinkConfigLowLatencyVideoOutput

Flag

Reduces output latency on some older products.
On newer products, this option will have no effect.

Int(64)

Adjust genlock timing pixel offset. If the device
supports wide genlock offset adjustment (see
BMDDeckLinkSupportsFullFrameReferenceInput
TimingOffset attribute) then the supported range is
between +/half the count of total pixels in the video frame.
Otherwise the supported range is +/511.

Int(64)The capture pass through mode specifies how themonitoring video output is generated while capture is inprogress. See BMDDeckLinkCapturePassthroughModefor the available modes.

Int(64)The output video connection. See BMDVideoConnection
for more details. Enabling video output on one
connection will enable output on other available
output connections which are compatible. The statusof active output connection can be queried with thissetting. Multiple video output connections can be
active simultaneously. When querying the enabled
video outputs, the returned integer is a bitmask of
BMDVideoConnection where the corresponding bit is set
for each active output connection. When setting active
video outputs, only one video output connection can be
enabled per call, ie, the integer argument must refer to asingle video output connection. Enabling multiple output
connections simultaneously requires multiple calls.

bmdDeckLinkConfigReferenceInputTimingOffset

bmdDeckLinkConfigCapturePassThroughMode

bmdDeckLinkConfigVideoOutputConnection

Section 3 — Common Data Types

234

Name

Type

Description

bmdDeckLinkConfigVideoOutputConversionModeInt(64)

Settings for video output conversion.
The possible output modes are enumerated by
BMDVideoOutputConversionMode.

bmdDeckLinkConfigAnalogVideoOutputFlags

Int(64)

Settings for analog video output. BMDAnalogVideoFlags
enumerates the available analog video ﬂags.

bmdDeckLinkConfigVideoInputConnection

Int(64)The input video connection. Only one video input
connection can be active at a time.
See BMDVideoConnection for more details.

bmdDeckLinkConfigAnalogVideoInputFlags

Int(64)

The analog video input flags. See BMDAnalogVideoFlags
for more details.

bmdDeckLinkConfigVideoInputConversionModeInt(64)The video input conversion mode. See
BMDVideoInputConversionMode for more details.

bmdDeckLinkConfig32PulldownSequenceInitial
TimecodeFrame

Int(64)The A-frame setting for NTSC 23.98, which is used toappropriately adjust the timecode. The frame setting
range is between 0 and 29.

bmdDeckLinkConfigVANCSourceLine1MappingInt(64)The configuration of up to three lines of VANC to betransferred to or from the active picture on capture or
output. The acceptable range is between 0 and 30.
A value of 0 will disable the capture of that line.

bmdDeckLinkConfigVANCSourceLine2MappingInt(64)

The acceptable range is between 0 and 30.
A value of 0 will disable the capture of the line.

bmdDeckLinkConfigVANCSourceLine3MappingInt(64)

The acceptable range is between 0 and 30.
A value of 0 will disable the capture of the line.

bmdDeckLinkConfigAudioInputConnection

Int(64)The configuration of the audio input connection.
See BMDAudioConnection for more details.

bmdDeckLinkConfigAnalogAudioInputScaleChannel1
bmdDeckLinkConfigAnalogAudioInputScaleChannel2
bmdDeckLinkConfigAnalogAudioInputScaleChannel3

Float

The analog audio input scale in dB.
The supported range is between -12.00 and 12.00.

bmdDeckLinkConfigAnalogAudioInputScaleChannel4
bmdDeckLinkConfigDigitalAudioInputScale

Float

The digital audio input scale in dB. The acceptable range
is between -12.00 and 12.00.

bmdDeckLinkConfigAudioOutputAESAnalogSwitch

Int(64)The AES / analog audio output selection switch.
This is applicable only to cards that support switchable
analog audio outputs.

Float

The analog audio output scale in dB. The acceptable
range is between -12.00 and 12.00.

bmdDeckLinkConfigDigitalAudioOutputScale

Float

The digital audio output scale in dB. The acceptable
range is between -12.00 and 12.00.

bmdDeckLinkConfigDownConversionOn
AllAnalogOutput

Flag

Enable down conversion on all analog outputs.

bmdDeckLinkConfigSMPTELevelAOutput

Flag

Enable SMPTE level A output.

bmdDeckLinkConfigAnalogAudioOutputScaleChannel1
bmdDeckLinkConfigAnalogAudioOutputScaleChannel2
bmdDeckLinkConfigAnalogAudioOutputScaleChannel3
bmdDeckLinkConfigAnalogAudioOutputScaleChannel4

Set the label of the device. This can only be set
if the device has a persistent ID.
bmdDeckLinkConfigDeviceInformationLabelstringThis information will be saved onto the local machine but
not onto the device.
This information will also appear in Product Notes sectionof the Desktop Video Utility.

Section 3 — Common Data Types

235

Name

Type

Description
Set the serial number of the device. This can only be set if
the device has a persistent ID.

bmdDeckLinkConfigDeviceInformationSerialNumber

stringThis information will be saved onto the local machine but
not onto the device.
This information will also appear in Product Notes sectionof the Desktop Video Utility.
Set the device’s seller name. This can only be set
if the device has a persistent ID.

bmdDeckLinkConfigDeviceInformationCompany

stringThis information will be saved onto the local machine but
not onto the device.
This information will also appear in Product Notes sectionof the Desktop Video Utility.
Set the device’s seller phone number.
This can only be set if the device has a persistent ID.

bmdDeckLinkConfigDeviceInformationPhone

stringThis information will be saved onto the local machine but
not onto the device.
This information will also appear in Product Notes sectionof the Desktop Video Utility.
Set the device’s seller email address. This can only be set
if the device has a persistent ID.

bmdDeckLinkConfigDeviceInformationEmailstringThis information will be saved onto the local machine but
not onto the device.
This information will also appear in Product Notes sectionof the Desktop Video Utility.
Set the device’s purchase date. This can only be set if thedevice has a persistent ID.

bmdDeckLinkConfigDeviceInformationDate

stringThis information will be saved onto the local machine but
not onto the device.
This information will also appear in Product Notes sectionof the Desktop Video Utility.

bmdDeckLinkConfigVideoOutputIdleOperation

Int(64)

Video output idle control. See
BMDIdleVideoOutputOperation for more details.

bmdDeckLinkConfigSwapSerialRxTx

Flag

If set to true, the Rx and Tx lines of the RS422 port on the
DeckLink device will be swapped.

bmdDeckLinkConfigBypass

Int(64)The state of the bypass feature. This parameter canbe set to a value of -1 for normal operation or zero to
bypass the card. A timeout of up to 65 seconds may be
specified in milliseconds. If the timeout is reached without
the parameter being reset, the card will be bypassed
automatically. The actual timeout will be approximately
the time requested.

bmdDeckLinkConfigClockTimingAdjustment

Int(64)Clock frequency adjustment for fine output control.
The acceptable range is from -127 to 127 PPM (Parts Per
Million).

bmdDeckLinkConfigVideoInputScanningFlag

The video input connector scanning on the H.264 Pro
Recorder. True if enabled.

bmdDeckLinkConfigUseDedicatedLTCInput

Flag

Use the timecode from the LTC input rather than from the
SDI stream.

bmdDeckLinkConfigDefaultVideoOutputModeInt(64)The default video output mode.
The bmdDeckLinkConfigDefaultVideoOutputModeFlags
must be set for 3D video modes before using this setting.
See BMDDisplayMode for more details.

bmdDeckLinkConfigDefaultVideoOutputModeFlags

Int(64)The default video output mode 2D or 3D flagsetting. See bmdVideoOutputFlagDefault andbmdVideoOutputDualStream3D for more details.

Section 3 — Common Data Types

236

Name

Type

Description

bmdDeckLinkConfigSDIOutputLinkConfiguration

Int(64)The SDI link configuration for a single output video
stream. See BMDLinkConfiguration for more information.

Float

The component video output luma gain in dB.
The accepted range can be determined by using the
BMDDeckLinkVideoOutputGainMinimumand BMDDeckLinkVideoOutputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The component video output chroma blue gain in
dB.The accepted range can be determined by using
the BMDDeckLinkVideoOutputGainMinimumand BMDDeckLinkVideoOutputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The component video output chroma red gain in dB.
The accepted range can be determined by using the
BMDDeckLinkVideoOutputGainMinimumand BMDDeckLinkVideoOutputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The composite video output luma gain in dB.
The accepted range can be determined by using the
BMDDeckLinkVideoOutputGainMinimumand BMDDeckLinkVideoOutputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The composite video output chroma gain in dB.
The accepted range can be determined by using the
BMDDeckLinkVideoOutputGainMinimumand BMDDeckLinkVideoOutputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The s-video output luma gain in dB.
The accepted range can be determined by using the
BMDDeckLinkVideoOutputGainMinimumand BMDDeckLinkVideoOutputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The s-video output chroma gain in dB.
The accepted range can be determined by using the
BMDDeckLinkVideoOutputGainMinimumand BMDDeckLinkVideoOutputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The component video input luma gain in dB.
The accepted range can be determined by using
the BMDDeckLinkVideoInputGainMinimum and
BMDDeckLinkVideoInputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The component video input chroma blue gain in dB.
The accepted range can be determined by using
the BMDDeckLinkVideoInputGainMinimum and
BMDDeckLinkVideoInputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The component video input chroma red gain in dB.
The accepted range can be determined by using
the BMDDeckLinkVideoInputGainMinimum and
BMDDeckLinkVideoInputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

Float

The composite video input luma gain in dB.
The accepted range can be determined by using
the BMDDeckLinkVideoInputGainMinimum and
BMDDeckLinkVideoInputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

bmdDeckLinkConfigVideoOutputComponentLumaGain

bmdDeckLinkConfigVideoOutputComponent
ChromaBlueGain

bmdDeckLinkConfigVideoOutputComponent
ChromaRedGain

bmdDeckLinkConfigVideoOutputCompositeLumaGain

bmdDeckLinkConfigVideoOutputComposite
ChromaGain

bmdDeckLinkConfigVideoOutputSVideoLumaGain

bmdDeckLinkConfigVideoOutputSVideoChromaGain

bmdDeckLinkConfigVideoInputComponentLumaGain

bmdDeckLinkConfigVideoInputComponent
ChromaBlueGain

bmdDeckLinkConfigVideoInputComponent
ChromaRedGain

bmdDeckLinkConfigVideoInputCompositeLumaGain

Section 3 — Common Data Types

237

Name

Type

Description

Float

The composite video input chroma gain in dB.
The accepted range can be determined by using
the BMDDeckLinkVideoInputGainMinimum and
BMDDeckLinkVideoInputGainMaximum attributes with
IDeckLinkProfileAttributes interface.

Float

The s-video input luma gain in dB. The
accepted range can be determined by using
the BMDDeckLinkVideoInputGainMinimumand BMDDeckLinkVideoInputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

bmdDeckLinkConfigVideoInputSVideoChromaGain

Float

The s-video input chroma gain in dB. The
accepted range can be determined by using
the BMDDeckLinkVideoInputGainMinimumand BMDDeckLinkVideoInputGainMaximum attributeswith IDeckLinkProfileAttributes interface.

bmdDeckLinkConfigInternalKeyingAncillaryDataSourceInt(64)

Set the source of VANC and timecode for output
signal when internal keying is enabled(See BMDInternalKeyingAncillaryDataSource).

bmdDeckLinkConfigMicrophonePhantomPowerFlag

If set to true, the Microphone input will provide +48V
Phantom Power.

bmdDeckLinkConfigMicrophoneInputGain

Float

The microphone input gain in dB. The
acceptable range can be determined via
BMDDeckLinkMicrophoneInputGainMinimum and
BMDDeckLinkMicrophoneInputGainMaximum.
If set to 0dB, the microphone input will be muted.

bmdDeckLinkConfigHeadphoneVolume

Float

Set the headphone volume, acceptable range is between
0.0 (mute), to 1.0 (full volume)

bmdDeckLinkConfigDeckControlConnection

Int(64)

The active RS422 deck control connection. See
BMDDeckControlConnection for more information.

bmdDeckLinkConfigSDIInput3DPayloadOverride

Flag

If set to true, the device will capture two genlocked SDI
streams with matching video modes as a 3D stream.

bmdDeckLinkConfigRec2020Output

Flag

If set to true, device will output Rec.709 frames in
Rec.2020 colorspace (See BMDColorspace)

bmdDeckLinkConfigQuadLinkSDIVideoOutput
SquareDivisionSplit

Flag

If set to true, Quad-link SDI is output in Square Division
Quad Split mode.

Int(64)

Any 32-bit number to identify a capture group.
All devices supporting synchronized capture
with the same group number are started and stopped
together.

bmdDeckLinkConfigPlaybackGroupInt(64)

Any 32-bit number to identify a playback group.
All devices supporting synchronized playbackwith the same group number are started and stopped
together.

bmdDeckLinkConfigHDMITimecodePacking

Int(64)

Set the HDMI timecode packing format
for the video output stream(See BMDHDMITimecodePacking).

bmdDeckLinkConfigSwapHDMICh3AndCh4OnInput

Flag

If set, HDMI audio input channels 3 and 4 are swapped tosupport 5.1 audio channel ordering

bmdDeckLinkConfigSwapHDMICh3AndCh4OnOutput

Flag

If set, HDMI audio output channels 3 and 4 are swapped
to support 5.1 audio channel ordering

bmdDeckLinkConfigReferenceOutputModeInt(64)

The reference output video mode for DeckLink devices
where reference output does not follow SDI output(see BMDDisplayMode). Supports interlaced/progressivemodes up to 1080p30.

bmdDeckLinkConfigEthernetUseDHCP

Flag

For devices with Ethernet. The local interface assigns a
local IP address via DHCP, otherwise static.

bmdDeckLinkConfigVideoInputCompositeChromaGain

bmdDeckLinkConfigVideoInputSVideoLumaGain

bmdDeckLinkConfigCaptureGroup

Section 3 — Common Data Types

238

Name

Type

Description

bmdDeckLinkConfigEthernetPTPFollowerOnly

Flag

For devices that use PTP. Prevents the device fromnegotiating to become a PTP leader. False by default.

bmdDeckLinkConfigEthernetPTPUseUDPEncapsulation

Flag

For devices that use PTP. Sets if UDP Encapsulation will
be used, otherwise Ethernet Encapsulation will be used.

bmdDeckLinkConfigEthernetPTPPriority1

Int(64)For devices that use PTP. Sets PTP’s Priority1 field.
The supported range is 0 to 255 with default value 128.

bmdDeckLinkConfigEthernetPTPPriority2

Int(64)For devices that use PTP. Sets PTP’s Priority2 field.
The supported range is 0 to 255 with default value 128.

bmdDeckLinkConfigEthernetPTPDomain

Int(64)For devices that use PTP. Sets PTP’s Domain field.
The supported range is 0 to 127 with default value 127.

bmdDeckLinkConfigEthernetStaticLocalIPAddress

stringFor devices with Ethernet. Manual local IP address. Used
when bmdDeckLinkConfigEthernetUseDHCP is false.

bmdDeckLinkConfigEthernetStaticSubnetMask

stringFor devices with Ethernet. Manual subnet mask. Used
when bmdDeckLinkConfigEthernetUseDHCP is false.

bmdDeckLinkConfigEthernetStaticGatewayIPAddress

stringFor devices with Ethernet. Manual gateway IP address.
Used when bmdDeckLinkConfigEthernetUseDHCP isfalse.

bmdDeckLinkConfigEthernetStaticPrimaryDNS

stringFor devices with Ethernet. Manual primary DNS. Used
when bmdDeckLinkConfigEthernetUseDHCP is false.

bmdDeckLinkConfigEthernetStaticSecondaryDNS

stringFor devices with Ethernet. Manual secondary DNS. Used
when bmdDeckLinkConfigEthernetUseDHCP is false.

stringFor devices with Ethernet. Set the output address
for the video flow. Omission of either dotted-decimal
IP or colon-port represents auto for either, or empty
string for both. Get the actual used address from
bmdDeckLinkStatusEthernetVideoOutputAddress
status item.

stringFor devices with Ethernet. Set the output address
for the audio flow. Omission of either dotted-decimal
IP or colon-port represents auto for either, or empty
string for both. Get the actual used address from
bmdDeckLinkStatusEthernetAudioOutputAddress
status item.

bmdDeckLinkConfigEthernetAncillaryOutputAddress

stringFor devices with Ethernet. Set the output address forthe ancillary flow. Omission of either dotted-decimal
IP or colon-port represents auto for either, or empty
string for both. Get the actual used address from
bmdDeckLinkStatusEthernetAncillaryOutputAddress
status item.

bmdDeckLinkConfigEthernetAudioOutputChannelOrder

stringFor devices with Ethernet. Sets the output audio SDP
channel-order with the convention defined by ST 2110-30.

bmdDeckLinkConfigOutputValidateEDIDForDolbyVision

Flag

If set (default), process the sink EDID and potentially failoperations that aren’t supported.

bmdDeckLinkConfigVideoOutputConversion
ColorspaceDestination

Int(64)For colorspace conversion, the destination
BMDColorspace.

bmdDeckLinkConfigVideoOutputConversion
ColorspaceSourceInt(64)For colorspace conversion, the source BMDColorspace.
Frames in other colorspaces will not be converted.

bmdDeckLinkConfigDolbyVisionCMVersion

Float

A float represeting the Dolby Vision content mapping
version to use when Dolby Vision output is enabled.

bmdDeckLinkConfigDolbyVisionMasterMinimumNits

Float

A float represeting the mastering monitor minimum
brightness in nits.

bmdDeckLinkConfigDolbyVisionMasterMaximumNits

Float

A float represeting the mastering monitor maximum
brightness in nits.

bmdDeckLinkConfigEthernetVideoOutputAddress

bmdDeckLinkConfigEthernetAudioOutputAddress

Section 3 — Common Data Types

239

3.19

Audio Output Stream TypeBMDAudioOutputStreamType enumerates the Audio output stream type (seeIDeckLinkOutput::EnableAudioOutput for details).
— bmdAudioOutputStreamContinuous
Audio stream is continuous.
— bmdAudioOutputStreamTimestamped
Audio stream is time stamped.

3.20

Analog Video Flags
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 usedin 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.

3.21

Audio Connection Modes
BMDAudioConnection enumerates the possible audio connection interfaces.
— bmdAudioConnectionEmbedded
Embedded SDI or HDMI audio connection— bmdAudioConnectionAESEBU
AES/EBU audio connection— bmdAudioConnectionAnalog
Analog audio connection— bmdAudioConnectionAnalogXLR
Analog XLR audio connection— bmdAudioConnectionAnalogRCA
Analog RCA audio connection— bmdAudioConnectionMicrophone
Analog Microphone audio connection— bmdAudioConnectionHeadphones
Analog Headphone audio connection

3.22

Audio Output Selection switch
BMDAudioOutputAnalogAESSwitch enumerates the settings of the audio output Analog / AES switch.
Refer to the IDeckLinkConfiguration interface to get and set analog / AES switch settings.
— bmdAudioOutputSwitchAESEBU
AES / EBU audio output.
— bmdAudioOutputSwitchAnalog
Analog audio output.

Section 3 — Common Data Types

240

3.23

Output Conversion Modes
BMDVideoOutputConversionMode enumerates the possible video output conversions.
— bmdNoVideoOutputConversion
No video output conversion— bmdVideoOutputLetterboxDownconversion
Down-converted letterbox SD output— bmdVideoOutputAnamorphicDownconversion
Down-converted anamorphic SD output— bmdVideoOutputHD720toHD1080Conversion
HD720 to HD1080 conversion output— bmdVideoOutputHardwareLetterboxDownconversion
Simultaneous output of HD and down-converted letterbox SD— bmdVideoOutputHardwareAnamorphicDownconversion
Simultaneous output of HD and down-converted anamorphic SD— bmdVideoOutputHardwareCenterCutDownconversion
Simultaneous output of HD and center cut SD— bmdVideoOutputHardware720p1080pCrossconversion
The simultaneous output of 720p and 1080p cross-conversion— bmdVideoOutputHardwareAnamorphic720pUpconversion
The simultaneous output of SD and up-converted anamorphic 720p
— bmdVideoOutputHardwareAnamorphic1080iUpconversion
The simultaneous output of SD and up-converted anamorphic 1080i— bmdVideoOutputHardwareAnamorphic149To720pUpconversion
The simultaneous output of SD and up-converted anamorphic
widescreen aspect ratio 14:9 to 720p.
— bmdVideoOutputHardwareAnamorphic149To1080iUpconversion
The simultaneous output of SD and up-converted anamorphic
widescreen aspect ratio 14:9 to 1080i.
— bmdVideoOutputHardwarePillarbox720pUpconversion
The simultaneous output of SD and up-converted pillarbox 720p
— bmdVideoOutputHardwarePillarbox1080iUpconversion
The simultaneous output of SD and up-converted pillarbox 1080i

3.24

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

Section 3 — Common Data Types

241

3.25

Video Input Format Changed Events
BMDVideoInputFormatChangedEvents enumerates the properties of the video input signal format thathave changed. (See IDeckLinkInputCallback::VideoInputFormatChanged for details).
— bmdVideoInputDisplayModeChanged
Either the video input display mode (see BMDDisplayMode for details) or detected video input dual
stream 3D has changed (see BMDDetectedVideoInputFormatFlags for details).
— bmdVideoInputFieldDominanceChanged
Video input field dominance has changed (see BMDFieldDominance for details)— bmdVideoInputColorspaceChanged
Video input color space or depth has changed (see BMDDetectedVideoInputFormatFlags for details)

3.26

Detected Video Input Format Flags
BMDDetectedVideoInputFormatFlags enumerates the video input signal(See IDeckLinkInputCallback::VideoInputFormatChanged for details)— bmdDetectedVideoInputYCbCr422
The video input detected is YCbCr 4:2:2 represention.
— bmdDetectedVideoInputRGB444
The video input detected is RGB 4:4:4 represention.
— bmdDetectedVideoInputDualStream3D
The video input detected is dual stream 3D video.
— bmdDetectedVideoInput12BitDepth
The video input detected is 12-bit color depth.
— bmdDetectedVideoInput10BitDepth
The video input detected is 10-bit color depth.
— bmdDetectedVideoInput8BitDepth
The video input detected is 8-bit color depth.

3.27

Capture Pass Through Mode
BMDDeckLinkCapturePassthroughMode enumerates whether the video output is electrical connectedto the video input or if the clean switching mode is enabled.
— bmdDeckLinkCapturePassthroughModeDirect
In direct mode the monitoring video output is directly electrically connected to the video input.
— bmdDeckLinkCapturePassthroughModeCleanSwitch
In clean switch mode, the captured video is played back out the monitoring outputs allowing a clean
switch between monitoring and playback if the video modes are compatible. The monitoring output
signal is affected by the options specified on capture and some latency is introduced between capture
and monitoring.
— bmdDeckLinkCapturePassthroughModeDisabled
In disabled mode the video input is not displayed out the monitoring outputs, which instead display
black frames or the last frame played, dependant on the configuration of the Idle Output setting (seeBMDIdleVideoOutputOperation).

Section 3 — Common Data Types

242

3.28

Display Mode Characteristics
BMDDisplayModeFlags enumerates the possible characteristics of an IDeckLinkDisplayMode object.
— bmdDisplayModeSupports3D
The 3D equivalent of this display mode is supported by the installed DeckLink device.
— bmdDisplayModeColorspaceRec601
This display mode uses the Rec. 601 standard for encoding interlaced analogue video signals indigital form.
— bmdDisplayModeColorspaceRec709
This display mode uses the Rec. 709 standard for encoding high definition video content.
— bmdDisplayModeColorspaceRec2020
This display mode uses the Rec. 2020 standard for encoding ultra-high definition video content.

3.29

Video 3D packing format
The BMDVideo3DPackingFormat enumerates standard modes where two frames are packed into one.
— bmdVideo3DPackingSidebySideHalf
Frames are packed side-by-side as a single stream.
— bmdVideo3DPackingLinebyLine
The two eye frames are packed on alternating lines of the source frame.
— bmdVideo3DPackingTopAndBottom
The two eye frames are packed into the top and bottom half of the source frame.
— bmdVideo3DPackingFramePacking
Frame packing is a standard HDMI 1.4a 3D mode (Top / Bottom full).
— bmdVideo3DPackingLeftOnly
Only the left eye frame is displayed.
— bmdVideo3DPackingRightOnly
Only the right eye frame is displayed.

3.30

Timecode Format
BMDTimecodeFormat enumerates the possible video frame timecode formats.
— bmdTimecodeRP188VITC1
RP188 VITC1 timecode (DBB1=1) on line 9.
— bmdTimecodeRP188VITC2
RP188 VITC2 timecode (DBB1=2) on line 571.
— bmdTimecodeRP188LTC
RP188 LTC timecode (DBB1=0) on line 10, or the dedicated LTC input if
bmdDeckLinkConfigUseDedicatedLTCInput is true.
— bmdTimecodeRP188HighFrameRate
RP188 HFR timecode (DBB1=8xh)— bmdTimecodeRP188Any
In capture mode the first valid RP188 timecode will be returned. In playback mode the timecode is set
as RP188 VITC1.
— bmdTimecodeVITC
VITC timecode field 1.
— bmdTimecodeVITCField2
VITC timecode field 2.
— bmdTimecodeSerial
Serial timecode.

Section 3 — Common Data Types

243

3.31

Timecode Flags
BMDTimecodeFlags enumerates the possible flags that accompany a timecode.
— bmdTimecodeFlagDefault
timecode is a non-drop timecode— bmdTimecodeIsDropFrame
timecode is a drop timecode— bmdTimecodeFieldMark
timecode field mark flag used with frame rates above 30 FPS— bmdTimecodeColorFrame
timecode color frame frame flag
— bmdTimecodeEmbedRecordingTrigger
timecode embeds recording trigger— bmdTimecodeRecordingTriggered
timecode recording is triggered flag

3.32

Timecode BCD
BMDTimecodeBCD is a 32-bit unsigned integer timecode encoded as HHMMSSFF. Each four bits
represent a single decimal digit:
digit

bit 3

bit 2

bit 1

bit 0

0

0

0

0

0

1

0

0

0

1

2

0

0

1

0

3

0

0

1

1

4

0

1

0

0

5

0

1

0

1

6

0

1

1

0

7

0

1

1

1

8

1

0

0

0

9

1

0

0

1

Word
Decreasing Address Order
Byte 4
Tens ofhours
7

6

Byte 3
Tens ofminutes

hours
5

4

3

2

1

0

7

6

5

Byte 2Tens ofseconds

minutes
4

3

2

1

0

7

6

5

Byte 1
Tens offramesseconds
4

3

2

1

0

7

6

frames
5

4

3

2

1

Section 3 — Common Data Types

0

244

3.33

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

3.34

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

3.35

Deck Control VTR Control States
BMDDeckControlVTRControlState enumerates the possible deck control VTR control states.
— bmdDeckControlNotInVTRControlMode
The deck is currently not in VTR control mode.
— bmdDeckControlVTRControlPlaying
The deck is currently playing.
— bmdDeckControlVTRControlRecording
The deck is currently recording.
— bmdDeckControlVTRControlStill
The deck is currently paused.
— bmdDeckControlVTRControlShuttleForward
The deck is currently in shuttle forward mode.
— bmdDeckControlVTRControlShuttleReverse
The deck is currently in shuttle reverse mode.
— bmdDeckControlVTRControlJogForward
The deck is currently in jog (one frame at a time) forward mode.
— bmdDeckControlVTRControlJogReverse
The deck is currently in jog (one frame at a time) reverse mode.
— bmdDeckControlVTRControlStopped
The deck is currently stopped.
Section 3 — Common Data Types

245

3.36

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

3.37

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

Section 3 — Common Data Types

246

3.38

Deck Control error
BMDDeckControlError enumerates the possible deck control errors.
— bmdDeckControlNoError— bmdDeckControlModeError
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— bmdDeckControlMissedInPointError
The in point was missed while prerolling as the current timecode has passed the begin in /capture timecode.
— bmdDeckControlDeckTimeoutError
Deck control timeout error.
— bmdDeckControlCommandFailedError
A deck control command request has failed.
— bmdDeckControlDeviceAlreadyOpenedError
The deck control device is already open.
— bmdDeckControlFailedToOpenDeviceError
Deck control failed to open the serial device.
— bmdDeckControlInLocalModeError
The deck in local mode and is no longer controllable.
— bmdDeckControlEndOfTapeError
Deck control has reached or is trying to move past the end of the tape.
— bmdDeckControlUserAbortError
Abort an export-to-tape or capture operation.
— bmdDeckControlNoTapeInDeckError
There is currently no tape in the deck.
— bmdDeckControlNoVideoFromCardError
A capture or export operation was attempted when the input signal was invalid.
— bmdDeckControlNoCommunicationError
The deck is not responding to requests.
— bmdDeckControlBufferTooSmallError
When sending a custom command, either the internal buffer is too small for the provided custom
command (reduce the size of the custom command), or the buffer provided for the command’s
response is too small (provide a larger one).
— bmdDeckControlBadChecksumError
When sending a custom command, the deck’s response contained an invalid checksum.
— bmdDeckControlUnknownError
Deck control unknown error.

3.39

Genlock Reference Status
BMDReferenceStatus enumerates the genlock reference statuses of the DeckLink device.
— bmdReferenceUnlocked
Genlock reference lock has not been achieved.
— bmdReferenceNotSupportedByHardware
The DeckLink device does not have a genlock input connector.
— bmdReferenceLocked
Genlock reference lock has been achieved.

Section 3 — Common Data Types

247

3.40

Idle Video Output Operation
BMDIdleVideoOutputOperation enumerates the possible output modes when idle.
— bmdIdleVideoOutputBlack
When not playing video, the device will output black frames.
— bmdIdleVideoOutputLastFrame
When not playing video, the device will output the last frame played.

3.41

Device Busy State
BMDDeviceBusyState enumerates the possible busy states for a device.
— bmdDeviceCaptureBusy
The device is currently being used for capture.
— bmdDevicePlaybackBusy
The device is currently being used for playback.
— bmdDeviceSerialPortBusy
The device’s serial port is currently being used.

3.42

DeckLink Device Notification
BMDNotifications enumerates the possible notifications for DeckLink devices.
— bmdPreferencesChanged
The preferences have changed. This occurs when IDeckLinkConfiguration::WriteToPreferences iscalled, or when the preference settings are saved in the Blackmagic Design Control Panel. The param1
and param2 parameters are 0.
— bmdStatusChanged
A status information item has changed. The param1 parameter contains the BMDDeckLinkStatusID of
the status information item which changed; param2 is 0. Use the IDeckLinkStatus interface to retrieve
the new status.

3.43

Streaming Device Mode
BMDStreamingDeviceMode enumerates the possible device modes for the streaming device.
— bmdStreamingDeviceIdle
The streaming device is idle.
— bmdStreamingDeviceEncoding
The streaming device is encoding.
— bmdStreamingDeviceStopping
The streaming device is stopping.
— bmdStreamingDeviceUnknown
The streaming device is in an unknown state.

Section 3 — Common Data Types

248

3.44

Streaming Device Encoding Frame Rates
BMDStreamingEncodingFrameRate enumerates the possible encoded frame rates of thestreaming device.
— bmdStreamingEncodedFrameRate50i
The encoded interlaced frame rate is 50 fields per second.
— bmdStreamingEncodedFrameRate5994i
The encoded interlaced frame rate is 59.94 fields per second.
— bmdStreamingEncodedFrameRate60i
The encoded interlaced frame rate is 60 fields per second.
— bmdStreamingEncodedFrameRate2398p
The encoded progressive frame rate is 23.98 frames per second.
— bmdStreamingEncodedFrameRate24p
The encoded progressive frame rate is 24 frames per second.
— bmdStreamingEncodedFrameRate25
The encoded progressive frame rate is 25 frames per second.
— bmdStreamingEncodedFrameRate2997p
The encoded progressive frame rate is 29.97 frames per second.
— bmdStreamingEncodedFrameRate30p
The encoded progressive frame rate is 30 frames per second.
— bmdStreamingEncodedFrameRate50p
The encoded progressive frame rate is 50 frames per second.
— bmdStreamingEncodedFrameRate5994p
The encoded progressive frame rate is 59.94 frames per second.
— bmdStreamingEncodedFrameRate60p
The encoded progressive frame rate is 60 frames per second.

3.45

Streaming Device Encoding Support
BMDStreamingEncodingSupport enumerates the possible types of support for an encoding mode.
— bmdStreamingEncodingModeNotSupported
The encoding mode is not supported.
— bmdStreamingEncodingModeSupported
The encoding mode is supported.
— bmdStreamingEncodingModeSupportedWithChanges
The encoding mode is supported with changes to encoding parameters.

3.46

Streaming Device Codecs
BMDStreamingVideoCodec enumerates the possible codecs that are supported by the streaming device.
— bmdStreamingVideoCodecH264
The H.264/AVC video compression codec.

Section 3 — Common Data Types

249

3.47

Streaming Device H264 Profile
BMDStreamingH264Profile enumerates the possible H.264 video coding profiles that are available on
the streaming device. Profiles indicate the complexity of algorithms and coding tools required by adecoder, with Baseline Profile requiring the lowest complexity decoder to decode the encoded video.
— bmdStreamingH264ProfileHigh
High Profile— bmdStreamingH264ProfileMain
Main Profile— bmdStreamingH264ProfileBaseline
Baseline Profile

3.48

Streaming Device H264 Level
BMDStreamingH264Level enumerates the possible H.264 video coding levels that are available on thestreaming device. Levels indicate bitrate and resolution constraints on a video decoder. Higher levels
require a decoder capable of decoding higher bitrates and resolutions than lower levels.
— bmdStreamingH264Level12
Level 1.2
— bmdStreamingH264Level13
Level 1.3
— bmdStreamingH264Level2
Level 2— bmdStreamingH264Level21
Level 2.1
— bmdStreamingH264Level22
Level 2.2
— bmdStreamingH264Level3— Level 3— bmdStreamingH264Level31
Level 3.1
— bmdStreamingH264Level32
Level 3.2
— bmdStreamingH264Level4
Level 4— bmdStreamingH264Level41
Level 4.1
— bmdStreamingH264Level42
Level 4.2

3.49

Streaming Device H264 Entropy Coding
BMDStreamingH264EntropyCoding enumerates the possible entropy coding options.
— bmdStreamingH264EntropyCodingCAVLC
Context-adaptive variable-length coding.
— bmdStreamingH264EntropyCodingCABAC
Context-adaptive binary arithmetic coding.

Section 3 — Common Data Types

250

3.50

Streaming Device Audio Codec
BMDStreamingAudioCodec enumerates the possible audio codecs.
— bmdStreamingAudioCodecAAC
MPEG Advanced Audio Coding (AAC).

3.51

Streaming Device Encoding Mode Properties
BMDStreamingEncodingModePropertyID enumerates the possible properties of the encoding mode.
— bmdStreamingEncodingPropertyVideoFrameRate
Video frame rate as a BMDStreamingEncodingFrameRate value— bmdStreamingEncodingPropertyVideoBitRateKbps
Video codec bitrate in kilobits per second— bmdStreamingEncodingPropertyH264Profile
Video codec profile as a BMDStreamingH264Profile value— bmdStreamingEncodingPropertyH264Level
Video codec level as a BMDStreamingH264Level value— bmdStreamingEncodingPropertyH264EntropyCodingVideo codec entropy coding as a BMDStreamingH264EntropyCoding value— bmdStreamingEncodingPropertyH264HasBFrames
Boolean value indicating whether B-Frames will be output by encoding mode
— bmdStreamingEncodingPropertyAudioCodec
Audio codec as a BMDStreamingAudioCodec value— bmdStreamingEncodingPropertyAudioSampleRate
Audio sampling rate in Hertz— bmdStreamingEncodingPropertyAudioChannelCount
Number of audio channels— bmdStreamingEncodingPropertyAudioBitRateKbps
Audio codec bitrate in kilobits per second

3.52

Audio Formats
BMDAudioFormat enumerates the audio formats supported for encoder capture— bmdAudioFormatPCM
Signed PCM samples, see BMDAudioSampleRate for the available sample rates andBMDAudioSampleType for the available sample sizes.

3.53

Deck Control Connection
BMDDeckControlConnection enumerates the possible deck control connections.
— bmdDeckControlConnectionRS422Remote1
First RS422 deck control connection— bmdDeckControlConnectionRS422Remote2
Second RS422 deck control connection

Section 3 — Common Data Types

251

3.54

Video Encoder Frame Coding Mode
BMDVideoEncoderFrameCodingMode enumerates the frame coding mode options.
— bmdVideoEncoderFrameCodingModeInter
Video frame data is compressed with reference to neighbouring video frame data.
— BmdVideoEncoderFrameCodingModeIntra
Video frame data is compressed relative to the current frame only.

3.55

DeckLink Encoder Configuration ID
BMDDeckLinkEncoderConfigurationID enumerates the set of video encoder configuration settings which
may be set or queried (see IDeckLinkEncoderConfiguration for details).
Name

Type

Description

bmdDeckLinkEncoderConfigPreferredBitDepth

Int(64)

Video encoder bit depth. Acceptable values are 8, 10,representing 8bit, 10bit respectively.

bmdDeckLinkEncoderConfigFrame CodingModeInt(64)

Video encoder frame coding mode. See
BMDVideoEncoderFrameCodingMode for more
information.

bmdDeckLinkEncoderConfigH265TargetBitrate

Int(64)

H.265 target bitrate. Acceptable range is between 2500
(2.5Mbit/s) and 50000000 (50Mbit/s).

bmdDeckLinkEncoderConfigMPEG4
SampleDescription

3.56

Codec configuration data represented as a full MPEG4
sample description (aka SampleEntry of an ‘stsd’ atom-box).
Useful for MediaFoundation, QuickTime, MKV and more.
Bytes

Note: The buffer returned by this configuration item
is only valid while encoded video input is enabled(i.e.IDeckLinkEncoderInput::EnableVideoInput
has been called).
Codec configuration data represented as sample
description extensions only (atom stream, each withsize and fourCC header). Useful for AVFoundation,
VideoToolbox, MKV and more.

bmdDeckLinkEncoderConfigMPEG4Codec
SpecificDesc

Bytes

bmdDeckLinkEncoderConfigDNxHRCompressionIDInt(64)DNxHR Compression ID.

bmdDeckLinkEncoderConfigDNxHRLevel

Int(64)DNxHR Level. BMDDNxHRLevel enumerates the available
DNxHR levels.

Note: The buffer returned by this configuration item
is only valid while encoded video input is enabled(i.e.IDeckLinkEncoderInput::EnableVideoInput
has been called).

Device Interface
BMDDeviceInterface enumerates the possible interfaces by which the device is connected.
— bmdDeviceInterfacePCI
PCI— bmdDeviceInterfaceUSBUSB— bmdDeviceInterfaceThunderbolt
Thunderbolt

Section 3 — Common Data Types

252

3.57

Packet Type
BMDPacketType enumerates the possible IDeckLinkEncoderPacket types.
— bmdPacketTypeStreamInterruptedMarker
A packet of this type marks when a video stream was interrupted.
— bmdPacketTypeStreamData
Regular stream data.

3.58

DeckLink Status ID
BMDDeckLinkStatusID enumerates the set of status information for a DeckLink device which may bequeried (see the IDeckLinkStatus interface for details).
Name

Type

Description

bmdDeckLinkStatusDetectedVideoInputMode

Int

The detected video input mode (BMDDisplayMode),available on devices which support input format detection.

bmdDeckLinkStatusDetectedVideoInputFormatFlags

Int

The detected video input format flags(BMDDetectedVideoInputFormatFlags), available ondevices which support input format detection.

bmdDeckLinkStatusDetectedVideoInputField
Dominance

Int

The field dominance of the detected video input mode
(BMDFieldDominance).

bmdDeckLinkStatusDetectedVideoInputColorspaceInt

The colorspace of the detected video input(BMDColorspace).

bmdDeckLinkStatusDetectedVideoInput
DynamicRangeInt

The dynamic range of the detected video input(BMDDynamicRange).

bmdDeckLinkStatusDetectedSDILinkConfigurationInt

The SDI video link configuration of the detected video input(BMDLinkConfiguration).

bmdDeckLinkStatusCurrentVideoInputMode

Int

The current video input mode (BMDDisplayMode).

bmdDeckLinkStatusCurrentVideoInputPixelFormat

Int

The current video input pixel format (BMDPixelFormat).

bmdDeckLinkStatusCurrentVideoInputFlags

Int

The current video input flags (BMDDeckLinkVideoStatusFlags)

bmdDeckLinkStatusCurrentVideoOutputMode

Int

The current video output mode (BMDDisplayMode).

bmdDeckLinkStatusCurrentVideoOutputFlags

Int

The current video output flags(BMDDeckLinkVideoStatusFlags).

bmdDeckLinkStatusEthernetLinkMbps

Int

For devices with Ethernet, the speed of the link in Mbps.

bmdDeckLinkStatusPCIExpressLinkWidthInt

PCIe link width, x1, x4, etc.

bmdDeckLinkStatusPCIExpressLinkSpeed

Int

PCIe link speed, Gen. 1, Gen. 2, etc.

bmdDeckLinkStatusLastVideoOutputPixelFormat

Int

The last video output pixel format (BMDPixelFormat).

bmdDeckLinkStatusReferenceSignalMode

Int

The detected reference input mode (BMDDisplayMode),available on devices which support reference input format
detection.

bmdDeckLinkStatusBusy

Int

The current busy state of the device. (See
BMDDeviceBusyState for more information).

bmdDeckLinkStatusVideoInputSignalLocked

Flag

True if the video input signal is locked.

bmdDeckLinkStatusReferenceSignalLocked

Flag

True if the reference input signal is locked.

bmdDeckLinkStatusReferenceSignalFlags

Int

The detected reference input flags(BMDDeckLinkVideoStatusFlags), available on devices
which support reference input format detection.

Section 3 — Common Data Types

253

Name

Type

Description

bmdDeckLinkStatusInterchangeablePanelType

Int

The interchangeable panel installed (BMDPanelType).

bmdDeckLinkStatusReceivedEDID

Bytes

The received EDID of a connected HDMI sink device.

bmdDeckLinkStatusDeviceTemperatureInt

The on-board temperature (ºC).

bmdDeckLinkStatusEthernetLink

Int

For devices with Ethernet, the state of the link
(BMDEthernetLinkState).

StringFor devices with Ethernet, the current negotiated or static
local IP address. Valid if bmdDeckLinkStatusEthernetLink
is bmdEthernetLinkStateConnectedBound. For other linkstates, this returns S_FALSE and an empty string.

StringFor devices with Ethernet, the current negotiated or static
subnet mask. Valid if bmdDeckLinkStatusEthernetLink is
bmdEthernetLinkStateConnectedBound. For other linkstates, this returns S_FALSE and an empty string.

StringFor devices with Ethernet, the current negotiated or static
gateway IP address. Valid if bmdDeckLinkStatusEthernetLink
is bmdEthernetLinkStateConnectedBound. For other linkstates, or unassigned, this returns S_FALSE and an empty string.

StringFor devices with Ethernet, the current negotiated or static primary
DNS IP address. Valid if bmdDeckLinkStatusEthernetLink
is bmdEthernetLinkStateConnectedBound. For other linkstates, or unassigned, this returns S_FALSE and an empty string.

bmdDeckLinkStatusEthernetSecondaryDNS

StringFor devices with Ethernet, the current negotiated or static secondary
DNS IP address. Valid if bmdDeckLinkStatusEthernetLink is
bmdEthernetLinkStateConnectedBound. For other link states,or unassigned, this returns S_FALSE and an empty string.

bmdDeckLinkStatusEthernetPTPGrandmasterIdentity

StringFor devices with Ethernet, the current negotiated PTP
grandmaster clock identity. If no PTP lock then this returns
S_FALSE and an empty string.

bmdDeckLinkStatusEthernetVideoOutputAddress

StringFor devices with Ethernet, the video output destination address

bmdDeckLinkStatusEthernetAudioOutputAddress

StringFor devices with Ethernet, the audio output destination address

bmdDeckLinkStatusEthernetAncillaryOutputAddress

StringFor devices with Ethernet, the ancillary output destination address

bmdDeckLinkStatusEthernetAudioInputChannelOrder

StringFor devices with Ethernet, the input audio SDP channelorder as per ST 2110-30.

Int

The actual HDMI output mode (BMDDisplayMode). HDMI
output can drop down to lower modes such as when
dropping from FRL to lower FRL rates or TMDS protocol
when errors are encountered, this value indicates theactual mode being transmitted.

bmdDeckLinkStatusHDMIOutputActualFormatFlags

Int

Format flags representing the actual HDMI output(BMDFormatFlags). HDMI output can change to otherformats such as when dropping from FRL to lower FRL rates
or TMDS protocol when errors are encountered, this value
indicates the actual format being transmitted.

bmdDeckLinkStatusHDMIOutputFRLRateInt

The output FRL rate or 0 for TMDS.

bmdDeckLinkStatusHDMIInputFRLRateInt

The input FRL rate or 0 for TMDS.

bmdDeckLinkStatusHDMIOutputTMDSLineRate

Int

The line rate of HDMI output (MHz). Valid when using TMDS
protocol only.

bmdDeckLinkStatusSinkSupportsDolbyVision

Flag

Reports the Dolby Vision content mapping version
supported by the sink.

bmdDeckLinkStatusEthernetLocalIPAddress

bmdDeckLinkStatusEthernetSubnetMask

bmdDeckLinkStatusEthernetGatewayIPAddress

bmdDeckLinkStatusEthernetPrimaryDNS

bmdDeckLinkStatusHDMIOutputActualMode

Section 3 — Common Data Types

254

3.59

Video Status Flags
BMDDeckLinkVideoStatusFlags enumerates status flags associated with a video signal.
— bmdDeckLinkVideoStatusPsF
Progressive frames are encoded as PsF.
— bmdDeckLinkVideoStatusDualStream3D
The video signal is dual stream 3D video.

3.60

Duplex Mode
BMDDuplexMode enumerates the duplex mode associated with a profile.
— bmdDuplexFull
Capable of simultaneous playback and capture.
— bmdDuplexHalf
Capable of playback or capture but not both simultaneously.
— bmdDuplexSimplex
Capable of playback only or capture only.
— bmdDuplexInactive
Device is inactive for this profile.

3.61

Frame Metadata ID
BMDDeckLinkFrameMetadataID enumerates the set of video frame metadata which may be queried fromthe IDeckLinkVideoFrameMetadataExtensions interface.
Name

Type

Description

bmdDeckLinkFrameMetadataHDRElectroOpticalTransferFunc

Int

EOTF in range 0-7 as per CEA 861.3

bmdDeckLinkFrameMetadataHDRDisplayPrimariesRedX

Float

Red display primaries in range 0.0 1.0

bmdDeckLinkFrameMetadataHDRDisplayPrimariesRedY

Float

Red display primaries in range 0.0 1.0

bmdDeckLinkFrameMetadataHDRDisplayPrimariesGreenX

Float

Green display primaries in range 0.0 1.0

bmdDeckLinkFrameMetadataHDRDisplayPrimariesGreenY

Float

Green display primaries in range 0.0 1.0

bmdDeckLinkFrameMetadataHDRDisplayPrimariesBlueX

Float

Blue display primaries in range 0.0 1.0

bmdDeckLinkFrameMetadataHDRDisplayPrimariesBlueY

Float

Blue display primaries in range 0.0 1.0

bmdDeckLinkFrameMetadataHDRWhitePointX

Float

White point in range 0.0 1.0

bmdDeckLinkFrameMetadataHDRWhitePointY

Float

White point in range 0.0 1.0

bmdDeckLinkFrameMetadataHDRMaxDisplay
MasteringLuminanceFloat

Max display mastering luminance in range
1 cd/m2 65535 cd/m2

bmdDeckLinkFrameMetadataHDRMinDisplay
MasteringLuminanceFloat

Min display mastering luminance in range
0.0001 cd/m2 6.5535 cd/m2

bmdDeckLinkFrameMetadataHDRMaximumContentLightLevel

Float

Maximum Content Light Level in range 1
cd/m2 65535 cd/m2

bmdDeckLinkFrameMetadataHDRMaximumFrame
AverageLightLevel

Float

Maximum Frame Average Light Level in range
1 cd/m2 65535 cd/m2

bmdDeckLinkFrameMetadataColorspace

Int

Colorspace of video frame(see BMDColorspace)

bmdDeckLinkFrameMetadataDolbyVision

Bytes

Dolby Vision Metadata

Section 3 — Common Data Types

255

3.62

DNxHR Levels
BMDDNxHRLevel enumerates the available DNxHR levels.
— bmdDNxHRLevelSQ
DNxHR Standard Quality— bmdDNxHRLevelLB
DNxHR Low Bandwidth— bmdDNxHRLevelHQ
DNxHR High Quality (8 bit)— bmdDNxHRLevelHQX
DNxHR High Quality (12 bit)— bmdDNxHRLevel444
DNxHR 4:4:4

3.63

Panel Type
BMDPanelType enumerates the type of interchangeable panel installed— bmdPanelNotDetected
No panel detected— bmdPanelTeranexMiniSmartPanel
Teranex Mini Smart Panel detected

3.64

Ancillary Packet Format
BMDAncillaryPacketFormat enumerates the possible data formats of the ancillary packet.
— bmdAncillaryPacketFormatUInt8
8-bit unsigned integer— bmdAncillaryPacketFormatUInt16
16-bit unsigned integer— bmdAncillaryPacketFormatYCbCr10
Native v210 pixel format (see bmdFormat10BitYUV for packing structure).

3.65

Colorspace
BMDColorspace enumerates the colorspace for a video frame.
— bmdColorspaceRec601
Rec. 601 colorspace— bmdColorspaceRec709
Rec. 709 colorspace— bmdColorspaceRec2020
Rec. 2020 colorspace— bmdColorspaceDolbyVisionNative
Colorspace defined by Dolby Vision version and metadata. Not supported for output unless used as
bmdDeckLinkConfigVideoOutputConversionColorspaceDestination with 12-bit RGB frames— bmdColorspaceP3D65
P3 colorspace with D65 white point. Not natively supported for output. Frames can only be provided
when this is set as bmdDeckLinkConfigVideoOutputConversionColorspaceSource and converted to
bmdDeckLinkConfigVideoOutputConversionColorspaceDestination.
— bmdColorspaceUnknown
Primary use is for disabling bmdDeckLinkConfigVideoOutputConversionColorspaceDestination

Section 3 — Common Data Types

256

3.66

HDMI Input EDID ID
BMDDeckLinkHDMIInputEDIDID enumerates the set of EDID items for a DeckLink HDMI input (see the
IDeckLinkHDMIInputEDID interface for details).

3.67

Name

Type

Description

bmdDeckLinkHDMIInputEDIDDynamicRangeInt

The dynamic range standards supported by the DeckLink
HDMI input (see BMDDynamicRange for more details)

Dynamic Range
BMDDynamicRange enumerates the possible dynamic range standards.
— bmdDynamicRangeSDR
Standard Dynamic Range— bmdDynamicRangeHDRStaticPQ
High Dynamic Range PQ (SMPTE ST 2084)— bmdDynamicRangeHDRStaticHLG
High Dynamic Range HLG (ITU-R BT.2100-0)

3.68

Supported Video Mode Flags
BMDSupportedVideoModeFlags enumerates the possible video mode flags when checking support with
IDeckLinkInput::DoesSupportVideoMode, IDeckLinkOutput:DoesSupportVideoMode andIDeckLinkEncoderInput::DoesSupportVideoMode methods.
— bmdSupportedVideoModeDefault
Check whether video mode is supported by device— bmdSupportedVideoModeKeying
Check whether keying is supported with video mode
— bmdSupportedVideoModeDualStream3D
Check whether dual-stream 3D is supported with video mode
— bmdSupportedVideoModeSDISingleLink
Check whether video mode is supported with single-link SDI connection— bmdSupportedVideoModeSDIDualLink
Check whether video mode is supported with dual-link SDI connection— bmdSupportedVideoModeSDIQuadLink
Check whether video mode is supported with quad-link SDI connection— bmdSupportedVideoModeInAnyProfile
Check whether video mode is supported with any device profile (by default only the current
profile is checked)— bmdSupportedVideoModePsF
Check whether device supports PsF interpretation of video mode (refer also to
bmdDeckLinkConfigOutput1080pAsPsF or bmdDeckLinkConfigCapture1080pAsPsF)— bmdSupportedVideoModeDolbyVision
Check whether video mode is supported with Dolby Vision

Section 3 — Common Data Types

257

3.69

Profile Identifier
BMDProfileID enumerates the possible profiles for a device.
— bmdProfileOneSubDeviceFullDuplex
Device with a single sub-device in full-duplex mode
— bmdProfileOneSubDeviceHalfDuplex
Device with a single sub-device in half-duplex mode
— bmdProfileTwoSubDevicesFullDuplex
Device with two sub-devices in full-duplex mode
— bmdProfileTwoSubDevicesHalfDuplex
Device with two sub-devices in half-duplex mode
— bmdProfileFourSubDevicesHalfDuplex
Device with four sub-devices in half-duplex mode

3.70

HDMI Timecode Packing
BMDHDMITimecodePacking enumerates the packing form of timecode for HDMI. IEEE OUI Vendor IDs
can be found at http://standards-oui.ieee.org/oui.txt— bmdHDMITimecodePackingIEEEOUI000085— bmdHDMITimecodePackingIEEEOUI080046— bmdHDMITimecodePackingIEEEOUI5CF9F0

3.71

Internal Keying Ancillary Data Source
BMDInternalKeyingAncillaryDataSource enumerates the source for VANC and timecode data when
performing internal keying.
— bmdInternalKeyingUsesAncillaryDataFromInputSignal
Output signal sources VANC and timecode from input signal— bmdInternalKeyingUsesAncillaryDataFromKeyFrame
Output signal sources VANC and timecode from key frame

3.72

Ethernet Link State
BMDEthernetLinkState enumerates the state of the Ethernet link.
— bmdEthernetLinkStateDisconnected
The physical Ethernet link is disconnected— bmdEthernetLinkStateConnectedUnboundEthernet is connected but not bound to an IP configuration— bmdEthernetLinkStateConnectedBound
Ethernet is connected and bound to an IP configuration

Section 3 — Common Data Types

258

3.73

Mezzanine Type
BMDMezzanineType enumerates the possible mezzanine boards which can be optionally attached tosome DeckLink devices.

NOTE Applications should check the available interfaces using
BMDDeckLinkVideoOutputConnections and BMDDeckLinkVideoInputConnections for a particularsubdevice rather than expecting interfaces here to be available on any particular subdevice.

— bmdMezzanineTypeNone
No mezzanine board— bmdMezzanineTypeHDMI14OpticalSDI
Mezzanine board with HDMI 1.4 and Optical SDI— bmdMezzanineTypeQuadSDI
Mezzanine board with four SDI connectors— bmdMezzanineTypeHDMI20OpticalSDI
Mezzanine board with HDMI 2.0 and Optical SDI— bmdMezzanineTypeHDMI21RS422
Mezzanine boards with HDMI 2.1 and RS422

3.74

Video Format Flags
BMDFormatFlags enumerates the possible flags for a pixel format.
— bmdFormatRGB444
The video is RGB 4:4:4 represention.
— bmdFormatYUV444
The video is YUV 4:4:4 represention.
— bmdFormatYUV422
The video is YUV 4:2:2 represention.
— bmdFormatYUV420
The video is YUV 4:2:0 represention.
— bmdFormat8BitDepth
The video is 8-bit color depth.
— bmdFormat10BitDepth
The video is 10-bit color depth.
— bmdFormat12BitDepth
The video is 12-bit color depth.

Section 3 — Common Data Types

259

© Copyright 2024 Blackmagic Design. All rights reserved. ‘Blackmagic’, ‘Blackmagic Design’, ‘DaVinci’,‘Resolve’, ‘DeckLink’, ‘HDLink’, ‘Videohub’, ‘Intensity’, ‘Ultrastudio’, ‘Teranex’, and ‘Leading the creative
video revolution’ are registered trademarks in the US and other countries. All other company and productnames may be trademarks of their respective companies with which they are associated. Thunderbolt andthe Thunderbolt logo are trademarks of Intel Corporation in the U.S. and/or other countries. Dolby, Dolby
Vision, and the double-D symbol are registered trademarks of Dolby Laboratories Licensing Corporation.

Section 3 — Common Data Types

260