2.5.3 IDeckLinkOutput Interface

The IDeckLinkOutput interface allows an application to output a video and audio stream from a DeckLink device.

An IDeckLinkOutput interface can be obtained from an IDeckLink interface using QueryInterface. If QueryInterface for an output interface is called on an input only device, then QueryInterface will fail and return E_NOINTERFACE.

Related Interfaces

Interface

Interface ID

Description

IDeckLink

IID_IDeckLink

An IDeckLinkOutput object interface may be obtained from IDeckLink using QueryInterface

IDeckLinkDisplayMode

IID_IDeckLinkDisplayMode

IDeckLinkOutput::GetDisplayMode() outputs an IDeckLinkDisplayMode object interface

IDeckLinkDisplayModeIterator

IID_IDeckLinkDisplayModeIterator

IDeckLinkOutput::GetDisplayModeIterator() outputs an IDeckLinkDisplayModeIterator object interface

IDeckLinkScreenPreviewCallback

IID_IDeckLinkScreenPreviewCallback

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

IDeckLinkMutableVideoFrame

IID_IDeckLinkMutableVideoFrame

IDeckLinkOutput::CreateVideoFrame() outputs an IDeckLinkMutableVideoFrame object interface

IDeckLinkMutableVideoFrame

IID_IDeckLinkMutableVideoFrame

IDeckLinkOutput::CreateVideoFrameWithBuffer() outputs an IDeckLinkMutableVideoFrame object interface

IDeckLinkVideoBuffer

IID_IDeckLinkVideoBuffer

An IDeckLinkVideoBuffer object interface is added to the newly created video frame with IDeckLinkOutput::CreateVideoFrameWithBuffer()

IDeckLinkVideoFrameAncillary

IID_IDeckLinkVideoFrameAncillary

IDeckLinkOutput::CreateAncillaryData() outputs an IDeckLinkVideoFrameAncillary object interface

IDeckLinkVideoFrame

IID_IDeckLinkVideoFrame

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

IDeckLinkVideoFrame

IID_IDeckLinkVideoFrame

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

IDeckLinkVideoOutputCallback

IID_IDeckLinkVideoOutputCallback

An IDeckLinkVideoOutputCallback object interface is registered with IDeckLinkOutput::SetScheduledFrameCompletionCallback()

IDeckLinkAudioOutputCallback

IID_IDeckLinkAudioOutputCallback

An IDeckLinkAudioOutputCallback object interface is registered with IDeckLinkOutput::SetAudioCallback()

IDeckLinkMacOutput

IID_IDeckLinkMacOutput

An IDeckLinkOutput object interface may be obtained from IDeckLinkMacOutput using QueryInterface

2.5.3.1 IDeckLinkOutput::DoesSupportVideoMode method

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

The DoesSupportVideoMode method indicates whether a given display mode is supported on output. If the requested video mode cannot 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 not account 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.

Parameters:

  • connection – Output connection to check, or bmdVideoConnectionUnspecified to check against any output 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 – Output conversion mode to check (see BMDVideoOutputConversionMode for details)

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

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

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

Return values:

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

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.2 IDeckLinkOutput::GetDisplayMode method

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

The GetDisplayMode method returns the IDeckLinkDisplayMode interface for an output 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.3.3 IDeckLinkOutput::GetDisplayModeIterator method

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

HRESULT IDeckLinkOutput::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 played.

Parameters:

previewCallback – The IDeckLinkScreenPreview object to be registered.

Return values:

  • E_OUTOFMEMORY – Unable to create kernel event (Windows only)

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.5 IDeckLinkOutput::EnableVideoOutput method

HRESULT IDeckLinkOutput::EnableVideoOutput(BMDDisplayMode displayMode, BMDVideoOutputFlags flags);

The EnableVideoOutput method puts the hardware into a specified video output mode. Once video output is enabled, frames may be displayed immediately with DisplayVideoFrameSync or scheduled with ScheduleVideoFrame.

Note

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

Parameters:

  • displayMode – Display mode for video output

  • flags – Flags to control ancillary data and video output features.

Return values:

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

  • E_OUTOFMEMORY – Insufficient memory for default frame allocator.

  • E_INVALIDARG – Parameter displayMode has an invalid value.

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.6 IDeckLinkOutput::DisableVideoOutput method

HRESULT IDeckLinkOutput::DisableVideoOutput();

The DisableVideoOutput method disables the hardware video output mode. The output is released for use by other IDeckLink instances.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.7 IDeckLinkOutput::CreateVideoFrame method

HRESULT IDeckLinkOutput::CreateVideoFrame(int32_t width, int32_t height, int32_t rowBytes, BMDPixelFormat pixelFormat, BMDFrameFlags flags, IDeckLinkMutableVideoFrame **outFrame);

The CreateVideoFrame method creates a new video frame with the specified parameters (see IDeckLinkMutableVideoFrame for more information) using a default-allocated buffer.

Parameters:

  • width – Frame width in pixels

  • height – Frame height in pixels

  • rowBytes – Bytes per row

  • pixelFormat – Pixel format

  • flags – Frame flags

  • outFrame – Newly created video frame

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.8 IDeckLinkOutput::CreateVideoFrameWithBuffer method

HRESULT IDeckLinkOutput::CreateVideoFrameWithBuffer(int32_t width, int32_t height, int32_t rowBytes, BMDPixelFormat pixelFormat, BMDFrameFlags flags, IDeckLinkVideoBuffer *buffer, IDeckLinkMutableVideoFrame **outFrame);

The CreateVideoFrameWithBuffer method creates a new video frame with the specified parameters (see IDeckLinkMutableVideoFrame for more information) using the buffer provided to it.

Parameters:

  • width – Frame width in pixels

  • height – Frame height in pixels

  • rowBytes – Bytes per row

  • pixelFormat – Pixel format

  • flags – Frame flags

  • buffer – Existing buffer for frame

  • outFrame – Newly created video frame

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.9 IDeckLinkOutput::RowBytesForPixelFormat method

HRESULT IDeckLinkOutput::RowBytesForPixelFormat(BMDPixelFormat pixelFormat, int32_t width, int32_t *rowBytes);

The RowBytesForPixelFormat method provides the frame row bytes for the requsted frame width and pixel format.

Tip

Applications implementing the IDeckLinkVideoBuffer interface must define buffers with a minimum size of RowBytesForPixelFormat x frame height.

Parameters:

  • pixelFormat – Pixel format

  • width – Frame width in pixels

  • rowBytes – Bytes per row

Return values:

  • E_INVALIDARG – The pixelFormat parameter is invalid

  • E_POINTER – The rowBytes parameter is a nullptr

  • S_OK – Success

2.5.3.10 IDeckLinkOutput::CreateAncillaryData method

HRESULT IDeckLinkOutput::CreateAncillaryData(BMDPixelFormat pixelFormat, IDeckLinkVideoFrameAncillary **outBuffer);

The CreateAncillaryData method creates an ancillary buffer that can be attached to an IDeckLinkMutableVideoFrame.

Tip

It is preferred that ancillary packets be attached to an output frame with the IDeckLinkVideoFrameAncillaryPackets interface.

Parameters:

  • pixelFormat – Pixel format for ancillary data

  • outBuffer – New video frame ancillary buffer

Return values:

  • E_ACCESSDENIED – Video output is not enabled.

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.11 IDeckLinkOutput::DisplayVideoFrameSync method

HRESULT IDeckLinkOutput::DisplayVideoFrameSync(IDeckLinkVideoFrame *theFrame);

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.

Parameters:

theFrame – Frame to display - after call return, the frame may be released

Return values:

  • E_ACCESSDENIED – Video output is not enabled.

  • E_INVALIDARG – The frame attributes are invalid.

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.12 IDeckLinkOutput::ScheduleVideoFrame method

HRESULT IDeckLinkOutput::ScheduleVideoFrame(IDeckLinkVideoFrame *theFrame, BMDTimeValue displayTime, BMDTimeValue displayDuration, BMDTimeScale timeScale);

The ScheduleVideoFrame method is used to schedule a frame for asynchronous playback at a specified time.

Video output must be enabled with EnableVideoOutput before frames can be displayed. Frames may be scheduled before calling StartScheduledPlayback to preroll. Once playback is initiated, new frames can be scheduled from IDeckLinkVideoOutputCallback.

Parameters:

  • theFrame – Frame to display

  • displayTime – Time at which to display the frame in timeScale units

  • displayDuration – Duration for which to display the frame in timeScale units

  • timeScale – Timescale for displayTime and displayDuration

Return values:

  • E_ACCESSDENIED – Video output is not enabled.

  • E_INVALIDARG – The frame attributes are invalid.

  • E_OUTOFMEMORY – Too many frames are already scheduled.

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.13 IDeckLinkOutput::SetScheduledFrameCompletionCallback method

HRESULT IDeckLinkOutput::SetScheduledFrameCompletionCallback(IDeckLinkVideoOutputCallback *theCallback);

The SetScheduledFrameCompletionCallback method configures a callback which will be called when each scheduled frame is completed or when scheduled playpack is stopped.

Parameters:

theCallback – Callback object implementing the IDeckLinkVideoOutputCallback interface

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.14 IDeckLinkOutput::GetBufferedVideoFrameCount method

HRESULT IDeckLinkOutput::GetBufferedVideoFrameCount(uint32_t *bufferedFrameCount);

The GetBufferedVideoFrameCount method gets the number of frames queued.

Parameters:

bufferedFrameCount – The frame count.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.15 IDeckLinkOutput::EnableAudioOutput method

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

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

Parameters:

  • sampleRate – Sample rate to output

  • sampleType – Sample type to output

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

  • streamType – Type of audio output stream.

Return values:

  • E_INVALIDARG – Invalid number of channels requested

  • E_ACCESSDENIED – Unable to access the hardware or audio output not enabled.

  • E_OUTOFMEMORY – Unable to create internal object

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.16 IDeckLinkOutput::DisableAudioOutput method

HRESULT IDeckLinkOutput::DisableAudioOutput();

The DisableAudioOutput method disables the hardware audio output mode.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.17 IDeckLinkOutput::WriteAudioSamplesSync method

HRESULT IDeckLinkOutput::WriteAudioSamplesSync(void *buffer, uint32_t sampleFrameCount, uint32_t *sampleFramesWritten);

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

Parameters:

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

  • sampleFrameCount – Number of sample frames available

  • sampleFramesWritten – Actual number of sample frames queued

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.18 IDeckLinkOutput::BeginAudioPreroll method

HRESULT IDeckLinkOutput::BeginAudioPreroll();

The BeginAudioPreroll method requests the driver begin polling the registered IDeckLinkAudioOutputCallback::RenderAudioSamples() interface for audio-preroll.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.19 IDeckLinkOutput::EndAudioPreroll method

HRESULT IDeckLinkOutput::EndAudioPreroll();

The EndAudioPreroll method requests the driver stop polling the registered IDeckLinkAudioOutputCallback interface for audio-preroll.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.20 IDeckLinkOutput::ScheduleAudioSamples method

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

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 less than the parameter sampleFrameCount.

Parameters:

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

  • sampleFrameCount – Number of sample frames available

  • streamTime –

    Time for audio playback in units of timeScale.

    When audio is enabled with bmdAudioOutputStreamContinuous, the streamTime and timeScale arguments may be set to 0 causing the samples to be queued immediately after any curently buffered samples.

  • timeScale – Time scale for the audio stream.

  • sampleFramesWritten – Actual number of sample frames scheduled

Return values:

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

  • E_INVALIDARG – An invalid timescale has been provided. When audio is enabled with bmdAudioOutputStreamTimestamped, a timescale is necessary as the audio packets are timestamped.

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.21 IDeckLinkOutput::GetBufferedAudioSampleFrameCount method

HRESULT IDeckLinkOutput::GetBufferedAudioSampleFrameCount(uint32_t *bufferedSampleFrameCount);

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.

Parameters:

bufferedSampleFrameCount – Number of audio frames currently buffered.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.22 IDeckLinkOutput::FlushBufferedAudioSamples method

HRESULT IDeckLinkOutput::FlushBufferedAudioSamples();

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.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.23 IDeckLinkOutput::SetAudioCallback method

HRESULT IDeckLinkOutput::SetAudioCallback(IDeckLinkAudioOutputCallback *theCallback);

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 packets may be scheduled by the application at any stage.

Parameters:

theCallback – Callback object implementing the IDeckLinkAudioOutputCallback interface

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.24 IDeckLinkOutput::StartScheduledPlayback method

HRESULT IDeckLinkOutput::StartScheduledPlayback(BMDTimeValue playbackStartTime, BMDTimeScale timeScale, double playbackSpeed);

The StartScheduledPlayback method starts scheduled playback. Frames may be pre-rolled by scheduling them before starting playback.

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 the scheduled frame’s display time.

Parameters:

  • playbackStartTime – Time at which the playback starts in units of timeScale

  • timeScale – Time scale for playbackStartTime and playbackSpeed.

  • playbackSpeed – Speed at which to play back : 1.0 is normal playback, -1.0 is reverse playback. Fast or slow forward or reverse playback may also be specified.

Return values:

  • E_INVALIDARG – Either parameters playbackStartTime or timeScale are invalid

  • E_ACCESSDENIED – The video output is not enabled

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.25 IDeckLinkOutput::StopScheduledPlayback method

HRESULT IDeckLinkOutput::StopScheduledPlayback(BMDTimeValue stopPlaybackAtTime, BMDTimeValue *actualStopTime, BMDTimeScale timeScale);

The StopScheduledPlayback method stops scheduled playback immediately or at a specified time. Any frames or audio scheduled after the stop time will be flushed.

Parameters:

  • stopPlaybackAtTime – Playback time at which to stop in units of timeScale. Specify 0 to stop immediately.

  • actualStopTime – Playback time at which playback actually stopped in units of timeScale.

  • timeScale – Time scale for stopPlaybackAtTime and actualStopTime. This value may be 0 if stopPlaybackAtTime is also 0.

Return values:

  • E_INVALIDARG – Either parameters stopPlaybackAtTime or timeScale are inavalid

  • E_ACCESSDENIED – The video output is not enabled

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.26 IDeckLinkOutput::IsScheduledPlaybackRunning method

HRESULT IDeckLinkOutput::IsScheduledPlaybackRunning(Boolean *active);

The IsScheduledPlaybackRunning method is called to determine if the driver’s video output scheduler is currently active.

Parameters:

active – Active status of video output scheduler

Return values:

  • E_INVALIDARG – Parameter active status variable is NULL.

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.27 IDeckLinkOutput::GetScheduledStreamTime method

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

The GetScheduledStreamTime method returns the stream time of the current scheduled frame. The stream time will be 0 if StartScheduledPlayback has not yet been called.

Parameters:

  • desiredTimeScale – Time scale for streamTime

  • streamTime – Frame time

  • playbackSpeed – Scheduled playback speed

Return values:

  • E_INVALIDARG – Parameter desiredTimeScale variable is invalid.

  • E_ACCESSDENIED – Video output is not enabled

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.28 IDeckLinkOutput::GetReferenceStatus method

HRESULT IDeckLinkOutput::GetReferenceStatus(BMDReferenceStatus *referenceStatus);

The GetReferenceStatus method provides the genlock reference status of the DeckLink device. The use of attribute ID BMDDeckLinkHasReferenceInput and status ID bmdDeckLinkStatusReferenceSignalLocked is preferred.

Parameters:

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

Return values:

  • E_POINTER – The parameter is invalid.

  • E_FAIL – Failure

  • S_OK – Success

2.5.3.29 IDeckLinkOutput::GetHardwareReferenceClock method

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

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 only be called while video output is enabled.

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

2.5.3.30 IDeckLinkOutput::GetFrameCompletionReferenceTimestamp method

HRESULT IDeckLinkOutput::GetFrameCompletionReferenceTimestamp(IDeckLinkVideoFrame *theFrame, BMDTimeScale desiredTimeScale, BMDTimeValue *frameCompletionTimestamp);

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 the frame referenced by the Frame pointer has not been re-scheduled.

Parameters:

  • theFrame – The video frame

  • desiredTimeScale – Desired timescale

  • frameCompletionTimestamp – Timestamp that the frame completed (in units of desiredTimeScale).

Return values:

  • E_UNEXPECTED – A timestamp for the specified frame is not available.

  • S_OK – Success