2.5.4 IDeckLinkInput Interface

The IDeckLinkInput interface allows an application to capture a video and audio stream from a DeckLink device.

An IDeckLinkInput interface can be obtained from an IDeckLink 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 interface. Audio capture is optional and can be handled by using the same callback.

Related Interfaces

Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkInput object interface may be obtained from IDeckLink using QueryInterface

IDeckLinkDisplayMode

IID_IDeckLinkDisplayMode

IDeckLinkInput::GetDisplayMode() outputs an IDeckLinkDisplayMode object interface

IDeckLinkDisplayModeIterator

IID_IDeckLinkDisplayModeIterator

IDeckLinkInput::GetDisplayModeIterator() outputs an IDeckLinkDisplayModeIterator object interface

IDeckLinkScreenPreviewCallback

IID_IDeckLinkScreenPreviewCallback

An IDeckLinkScreenPreviewCallback object interface is registered with IDeckLinkInput::SetScreenPreviewCallback()

IDeckLinkVideoBufferAllocatorProvider

IID_IDeckLinkVideoBufferAllocatorProvider

An IDeckLinkVideoBufferAllocatorProvider object interface is registered with IDeckLinkInput::EnableVideoInputWithAllocatorProvider()

IDeckLinkInputCallback

IID_IDeckLinkInputCallback

An IDeckLinkInputCallback object interface is registered with IDeckLinkInput::SetCallback()

2.5.4.1 IDeckLinkInput::DoesSupportVideoMode method

HRESULT IDeckLinkInput::DoesSupportVideoMode(BMDVideoConnection connection, BMDDisplayMode requestedMode, BMDPixelFormat requestedPixelFormat, BMDVideoInputConversionMode conversionMode, BMDSupportedVideoModeFlags flags, BMDDisplayMode *actualMode, Boolean *supported);

The DoesSupportVideoMode method indicates whether a given display mode is supported on input.

Parameters:

  • connection – Input connection to check, or bmdVideoConnectionUnspecified to check against any input connection (see BMDVideoConnection for details).

  • requestedMode – Display mode to check

  • requestedPixelFormat – Pixel format to check, or bmdFormatUnspecified to check against any pixel format (see BMDPixelFormat for details).

  • conversionMode – Input conversion mode to check (see BMDVideoInputConversionMode for details)

  • flags – Input video mode flags (see BMDSupportedVideoModeFlags for details).

  • actualMode – If this parameter is not NULL and the display mode is supported, the actual input display mode is returned.

  • supported – Returns true if the display mode is supported.

Return values:

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

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.2 IDeckLinkInput::GetDisplayMode method

HRESULT IDeckLinkInput::GetDisplayMode(BMDDisplayMode displayMode, IDeckLinkDisplayMode **resultDisplayMode);

The GetDisplayMode method returns the IDeckLinkDisplayMode interface for an input display mode identifier.

Parameters:

  • displayMode – The display mode ID (See BMDDisplayMode)

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

Return values:

  • 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.4.3 IDeckLinkInput::GetDisplayModeIterator method

HRESULT IDeckLinkInput::GetDisplayModeIterator(IDeckLinkDisplayModeIterator **iterator);

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

Parameters:

iterator – Display mode iterator

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.4 IDeckLinkInput::SetScreenPreviewCallback method

HRESULT IDeckLinkInput::SetScreenPreviewCallback(IDeckLinkScreenPreviewCallback *previewCallback);

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

Parameters:

previewCallback – The IDeckLinkScreenPreview object to be registered.

Return values:

S_OK – Success

2.5.4.5 IDeckLinkInput::EnableVideoInput method

HRESULT IDeckLinkInput::EnableVideoInput(BMDDisplayMode displayMode, BMDPixelFormat pixelFormat, BMDVideoInputFlags flags);

The EnableVideoInput method puts the hardware into a specified video input mode. Video input (and optionally audio input) is started by calling StartStreams.

Note

EnableVideoInput will provide an application exclusive access to the hardware input, calls to EnableVideoInput from other IDeckLink instances will return E_ACCESSDENIED.

Parameters:

  • displayMode – Video mode to capture

  • pixelFormat – Pixel format to capture

  • flags – Capture flags

Return values:

  • E_INVALIDARG – Is returned on invalid mode or video flags

  • E_ACCESSDENIED – Unable to access the hardware. This will occur if the input is already in use.

  • E_OUTOFMEMORY – Insufficient memory for default frame allocator.

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.6 IDeckLinkInput::EnableVideoInputWithAllocatorProvider method

HRESULT IDeckLinkInput::EnableVideoInputWithAllocatorProvider(BMDDisplayMode displayMode, BMDPixelFormat pixelFormat, BMDVideoInputFlags flags, IDeckLinkVideoBufferAllocatorProvider *allocatorProvider);

Optionally do the same as the EnableVideoInput method but instead allows the application developer to implement their own custom buffer allocators.

Parameters:

  • displayMode – Video mode to capture

  • pixelFormat – Pixel format to capture

  • flags – Capture flags

  • allocatorProvider – Provides the callback for custom allocators

Return values:

  • E_INVALIDARG – Is returned on invalid mode or video flags

  • E_ACCESSDENIED – Unable to access the hardware. This will occur if the input is already in use.

  • E_OUTOFMEMORY – Insufficient memory for default frame allocator.

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.7 IDeckLinkInput::DisableVideoInput method

HRESULT IDeckLinkInput::DisableVideoInput();

The DisableVideoInput method disables the hardware video capture mode.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.8 IDeckLinkInput::GetAvailableVideoFrameCount method

HRESULT IDeckLinkInput::GetAvailableVideoFrameCount(uint32_t *availableFrameCount);

The GetAvailableVideoFrameCount method provides the number of input video frames that are queued to be delivered to the IDeckLinkInputCallback::VideoInputFrameArrived() callback.

Parameters:

availableFrameCount – Number of available input frames.

Return values:

S_OK – Success

2.5.4.9 IDeckLinkInput::EnableAudioInput method

HRESULT IDeckLinkInput::EnableAudioInput(BMDAudioSampleRate sampleRate, BMDAudioSampleType sampleType, uint32_t channelCount);

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

Parameters:

  • sampleRate – Sample rate to capture

  • sampleType – Sample type to capture

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

Return values:

  • E_INVALIDARG – Invalid number of channels requested.

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.10 IDeckLinkInput::DisableAudioInput method

HRESULT IDeckLinkInput::DisableAudioInput();

The DisableAudioInput method disables the hardware audio capture mode.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.11 IDeckLinkInput::GetAvailableAudioSampleFrameCount method

HRESULT IDeckLinkInput::GetAvailableAudioSampleFrameCount(uint32_t *availableSampleFrameCount);

The GetAvailableAudioSampleFrameCount method returns the number of audio sample frames currently buffered.

Parameters:

availableSampleFrameCount – The number of buffered audio frames currently available.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.12 IDeckLinkInput::StartStreams method

HRESULT IDeckLinkInput::StartStreams();

The StartStreams method starts video and audio capture as configured with EnableVideoInput and optionally EnableAudioInput.

Return values:

  • E_ACCESSDENIED – Input stream is already running.

  • E_UNEXPECTED – Neither video or audio inputs have been enabled.

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.13 IDeckLinkInput::StopStreams method

HRESULT IDeckLinkInput::StopStreams();

The StopStreams method stops video and audio capture.

Return values:

  • E_ACCESSDENIED – Input stream already stopped.

  • S_OK – Success

2.5.4.14 IDeckLinkInput::PauseStreams method

HRESULT IDeckLinkInput::PauseStreams();

The PauseStreams method pauses video and audio capture. Capture time continues while the streams are paused but no video or audio will be captured.

Paused capture may be resumed by calling PauseStreams again. Capture may also be resumed by calling StartStreams but capture time will be reset.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.15 IDeckLinkInput::FlushStreams method

HRESULT IDeckLinkInput::FlushStreams();

The FlushStreams method removes any buffered video and audio frames.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.16 IDeckLinkInput::SetCallback method

HRESULT IDeckLinkInput::SetCallback(IDeckLinkInputCallback *theCallback);

The SetCallback method configures a callback which will be called for each captured frame.

Parameters:

theCallback – Callback object implementing the IDeckLinkInputCallback interface.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.4.17 IDeckLinkInput::GetHardwareReferenceClock method

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

The GetHardwareReferenceClock method returns a clock that is locked to the system clock.

The absolute values returned by this method are meaningless, however the relative differences between subsequent calls can be used to determine elapsed time.

This method can be called while video input is enabled (see IDeckLinkInput::EnableVideoInput() for details).

Parameters:

  • desiredTimeScale – Desired time scale

  • hardwareTime – Hardware reference time (in units of desiredTimeScale)

  • timeInFrame – Time elapsed since the start of the frame (in units of desiredTimeScale)

  • ticksPerFrame – Number of ticks for a frame (in units of desiredTimeScale)

Return values:

  • E_FAIL – Failure

  • S_OK – Success