2.5.28 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

IDeckLink

IID_IDeckLink

An IDeckLinkDeckControl object interface may be obtained from IDeckLink using QueryInterface

IDeckLinkTimecode

IID_IDeckLinkTimecode

IDeckLinkDeckControl::GetTimecode() outputs an IDeckLinkTimecode object interface

IDeckLinkDeckControlStatusCallback

IID_IDeckLinkDeckControlStatusCallback

An IDeckLinkDeckControlStatusCallback object interface is registered with IDeckLinkDeckControl::SetCallback()

2.5.28.1 IDeckLinkDeckControl::Open method

HRESULT IDeckLinkDeckControl::Open(BMDTimeScale timeScale, BMDTimeValue timeValue, Boolean timecodeIsDropFrame, BMDDeckControlError *error);

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 the deck control functionality.

Parameters:

  • timeScale – The time scale.

  • timeValue – The time value in units of BMDTimeScale.

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

  • error – The error code from the deck - see BMDDeckControlError for details.

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.2 IDeckLinkDeckControl::Close method

HRESULT IDeckLinkDeckControl::Close(Boolean standbyOn);

The Close method will optionally place the deck in standby mode before closing the connection.

Parameters:

standbyOn – Place the deck into standby mode (TRUE) before disconnection.

Return values:

S_OK – Success

2.5.28.3 IDeckLinkDeckControl::GetCurrentState method

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

The GetCurrentState method will get the current state of the deck.

Parameters:
Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • S_OK – Success

2.5.28.4 IDeckLinkDeckControl::SetStandby method

HRESULT IDeckLinkDeckControl::SetStandby(Boolean standbyOn);

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.

Parameters:

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

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.28.5 IDeckLinkDeckControl::SendCommand method

HRESULT IDeckLinkDeckControl::SendCommand(uint8_t *inBuffer, uint32_t inBufferSize, uint8_t *outBuffer, uint32_t *outDataSize, uint32_t outBufferSize, BMDDeckControlError *error);

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 the checksum) is stored in the provided buffer.

Parameters:

  • inBuffer – The buffer containing the command packet to transmit.

  • inBufferSize – The size of the buffer containing the command packet to transmit.

  • outBuffer – The buffer to contain the response packet.

  • outDataSize – The size of the response data.

  • outBufferSize – The size of the buffer that will contain the response packet.

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

Return values:

  • 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.28.6 IDeckLinkDeckControl::Play method

HRESULT IDeckLinkDeckControl::Play(BMDDeckControlError *error);

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.

Parameters:

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

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.7 IDeckLinkDeckControl::Stop method

HRESULT IDeckLinkDeckControl::Stop(BMDDeckControlError *error);

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.

Parameters:

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

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.8 IDeckLinkDeckControl::TogglePlayStop method

HRESULT IDeckLinkDeckControl::TogglePlayStop(BMDDeckControlError *error);

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.

Parameters:

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

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.9 IDeckLinkDeckControl::Eject method

HRESULT IDeckLinkDeckControl::Eject(BMDDeckControlError *error);

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.

Parameters:

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

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.10 IDeckLinkDeckControl::GoToTimecode method

HRESULT IDeckLinkDeckControl::GoToTimecode(BMDTimecodeBCD timecode, BMDDeckControlError *error);

The GoToTimecode method will send a “go to timecode” command to the deck.

Parameters:

  • timecode – The timecode to go to.

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

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.11 IDeckLinkDeckControl::FastForward method

HRESULT IDeckLinkDeckControl::FastForward(Boolean viewTape, BMDDeckControlError *error);

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.

Parameters:

  • viewTape – View the tape (TRUE) or enable automatic selection of “tape view” or “end to end view” (FALSE)

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

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.12 IDeckLinkDeckControl::Rewind method

HRESULT IDeckLinkDeckControl::Rewind(Boolean viewTape, BMDDeckControlError *error);

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.

Parameters:

  • viewTape – View the tape (TRUE) or enable automatic selection of “tape view” or “end to end view” (FALSE)

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

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.13 IDeckLinkDeckControl::StepForward method

HRESULT IDeckLinkDeckControl::StepForward(BMDDeckControlError *error);

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.

Parameters:

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

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.14 IDeckLinkDeckControl::StepBack method

HRESULT IDeckLinkDeckControl::StepBack(BMDDeckControlError *error);

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.

Parameters:

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

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.15 IDeckLinkDeckControl::Jog method

HRESULT IDeckLinkDeckControl::Jog(double rate, BMDDeckControlError *error);

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.

Parameters:

  • rate – 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 – The error code sent by the deck - see BMDDeckControlError for details.

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.16 IDeckLinkDeckControl::Shuttle method

HRESULT IDeckLinkDeckControl::Shuttle(double rate, BMDDeckControlError *error);

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.

Parameters:

  • rate – 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 – The error code sent by the deck - see BMDDeckControlError for details.

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.17 IDeckLinkDeckControl::GetTimecodeString method

HRESULT IDeckLinkDeckControl::GetTimecodeString(string *currentTimeCode, BMDDeckControlError *error);

The GetTimecodeString method will return the current timecode in string format.

Parameters:

  • currentTimeCode – The current timecode in string format.

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

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.18 IDeckLinkDeckControl::GetTimecode method

HRESULT IDeckLinkDeckControl::GetTimecode(IDeckLinkTimecode **currentTimecode, BMDDeckControlError *error);

The GetTimecode method will return the current timecode in IDeckLinkTimecode format.

Parameters:
Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.19 IDeckLinkDeckControl::GetTimecodeBCD method

HRESULT IDeckLinkDeckControl::GetTimecodeBCD(BMDTimecodeBCD *currentTimecode, BMDDeckControlError *error);

The GetTimecodeBCD method will return the current timecode in BCD format.

Parameters:

  • currentTimecode – The timecode in BCD format.

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

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.20 IDeckLinkDeckControl::SetPreroll method

HRESULT IDeckLinkDeckControl::SetPreroll(uint32_t prerollSeconds);

The SetPreroll method will set the preroll time period.

Parameters:

prerollSeconds – The preroll period in seconds to set.

Return values:

S_OK – Success

2.5.28.21 IDeckLinkDeckControl::GetPreroll method

HRESULT IDeckLinkDeckControl::GetPreroll(uint32_t *prerollSeconds);

The GetPreroll method will get the preroll period setting.

Parameters:

prerollSeconds – The current preroll period.

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure

  • S_OK – Success

2.5.28.22 IDeckLinkDeckControl::SetExportOffset method

HRESULT IDeckLinkDeckControl::SetExportOffset(int32_t exportOffsetFields);

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

Parameters:

exportOffsetFields – The timecode offset in fields.

Return values:

S_OK – Success

2.5.28.23 IDeckLinkDeckControl::GetExportOffset method

HRESULT IDeckLinkDeckControl::GetExportOffset(int32_t *exportOffsetFields);

The GetExportOffset method will return the current setting of the export offset in fields.

Parameters:

exportOffsetFields – The current timecode offset in fields.

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • S_OK – Success

2.5.28.24 IDeckLinkDeckControl::GetManualExportOffset method

HRESULT IDeckLinkDeckControl::GetManualExportOffset(int32_t *deckManualExportOffsetFields);

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.

Parameters:

deckManualExportOffsetFields – The current timecode offset.

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • S_OK – Success

2.5.28.25 IDeckLinkDeckControl::SetCaptureOffset method

HRESULT IDeckLinkDeckControl::SetCaptureOffset(int32_t captureOffsetFields);

The capture offset may be used to compensate for a deck specific offset between the in-point and the time at which the capture starts.

Parameters:

captureOffsetFields – The timecode offset to set in fields.

Return values:

S_OK – Success

2.5.28.26 IDeckLinkDeckControl::GetCaptureOffset method

HRESULT IDeckLinkDeckControl::GetCaptureOffset(int32_t *captureOffsetFields);

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

Parameters:

captureOffsetFields – The current timecode offset in fields.

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • S_OK – Success

2.5.28.27 IDeckLinkDeckControl::StartExport method

HRESULT IDeckLinkDeckControl::StartExport(BMDTimecodeBCD inTimecode, BMDTimecodeBCD outTimecode, BMDDeckControlExportModeOpsFlags exportModeOps, BMDDeckControlError *error);

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 bmdDeckControlExportCompleteEvent in the IDeckLinkDeckControlStatusCallback::DeckControlEventReceived() will occur several frames from the “outTimecode”.

Resources may be released at this point or another export may be commenced.

Parameters:

  • inTimecode – The timecode to start the export sequence.

  • outTimecode – The timecode to stop the export sequence.

  • exportModeOps – The export mode operations see BMDDeckControlExportModeOpsFlags for details.

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

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.28 IDeckLinkDeckControl::StartCapture method

HRESULT IDeckLinkDeckControl::StartCapture(Boolean useVITC, BMDTimecodeBCD inTimecode, BMDTimecodeBCD outTimecode, BMDDeckControlError *error);

The StartCapture method starts a capture operation using the given parameters. Prior to calling this method, the input interface should be set up as normal (refer to the Capture and IDeckLinkInput interface sections), IDeckLinkDeckControl should be configured (see description below) and a connection to the deck established using IDeckLinkDeckControl::Open().

A callback object should be set using IDeckLinkDeckControl::SetCallback() and an offset period set using IDeckLinkDeckControl::SetCaptureOffset().

After StartCapture is called, the application must wait until the bmdDeckControlPrepareForCaptureEvent event is received via 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 the inTimecode and outTimecode timecodes.

The application must take into account that the serial timecode values should be adjusted by the value set using IDeckLinkDeckControl::SetCaptureOffset().

During this period IDeckLinkDeckControlStatusCallback will be called when deck control events occur.

At the completion of the capture operation the bmdDeckControlCaptureCompleteEvent event in the 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.

Parameters:

  • useVITC – If true use VITC as the source of timecodes.

  • inTimecode – The timecode to start the capture sequence.

  • outTimecode – The timecode to stop the capture sequence.

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

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.29 IDeckLinkDeckControl::GetDeviceID method

HRESULT IDeckLinkDeckControl::GetDeviceID(uint16_t *deviceId, BMDDeckControlError *error);

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

Parameters:

  • deviceId – The code for the device model.

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

Return values:

  • E_INVALIDARG – One or more parameters are invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.30 IDeckLinkDeckControl::Abort method

HRESULT IDeckLinkDeckControl::Abort();

The Abort operation is asynchronous. Completion is signaled with a bmdDeckControlAbortedEvent event.

Return values:

  • E_FAIL – Failure

  • S_OK – Success

2.5.28.31 IDeckLinkDeckControl::CrashRecordStart method

HRESULT IDeckLinkDeckControl::CrashRecordStart(BMDDeckControlError *error);

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

Parameters:

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

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.32 IDeckLinkDeckControl::CrashRecordStop method

HRESULT IDeckLinkDeckControl::CrashRecordStop(BMDDeckControlError *error);

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

Parameters:

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

Return values:

  • E_INVALIDARG – The parameter is invalid.

  • E_FAIL – Failure - check error parameter.

  • S_OK – Success

2.5.28.33 IDeckLinkDeckControl::SetCallback method

HRESULT IDeckLinkDeckControl::SetCallback(IDeckLinkDeckControlStatusCallback *callback);

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

Parameters:

callback – The callback object implementing the IDeckLinkDeckControlStatusCallback interface

Return values:

S_OK – Success