2.5.49 IDeckLinkMetalScreenPreviewHelper Interface

class IDeckLinkMetalScreenPreviewHelper

The IDeckLinkMetalScreenPreviewHelper interface may be used with a simple IDeckLinkScreenPreviewCallback implementation to provide a Metal-based preview rendering which is decoupled 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 the command 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];

• 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
IDeckLinkVideoFrame	IID_IDeckLinkVideoFrame	An IDeckLinkVideoFrame object interface is set for Metal preview with IDeckLinkMetalScreenPreviewHelper::SetFrame()

2.5.49.1 IDeckLinkMetalScreenPreviewHelper::Initialize method

HRESULT IDeckLinkMetalScreenPreviewHelper::Initialize(void *device);

The Initialize method should be called to initialize the Metal preview to use the given device.

Parameters:

device – Metal device object of type id<MTLDevice>.

Return values:

• E_POINTER – Device argument is null

• E_INVALIDARG – Device argument is invalid

• E_FAIL – Failure

• S_OK – Success

2.5.49.2 IDeckLinkMetalScreenPreviewHelper::Draw method

HRESULT IDeckLinkMetalScreenPreviewHelper::Draw(void *cmdBuffer, void *renderPassDescriptor, void *viewport);

The Draw method encodes commands to an MTLCommandBuffer to draw the last frame provided by SetFrame.

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 the drawing 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.

Since the drawing of frame may require synchronization with the GPU, the frame will be retained until the command buffer completes.

Parameters:

• cmdBuffer – Metal command buffer object of type id<MTLCommandBuffer>;.

• renderPassDescriptor – Metal render pass descriptor object of type MTLRenderPassDescriptor*.

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

Return values:

• E_POINTER – Required argument is null

• E_INVALIDARG – Invalid argument received

• E_FAIL – Failure

• S_OK – Success

2.5.49.3 IDeckLinkMetalScreenPreviewHelper::SetFrame method

HRESULT IDeckLinkMetalScreenPreviewHelper::SetFrame(IDeckLinkVideoFrame *theFrame);

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.

Parameters:

theFrame – Video Frame to preview

Return values:

• E_INVALIDARG – The preview frame is invalid

• E_FAIL – Failure

• S_OK – Success

2.5.49.4 IDeckLinkMetalScreenPreviewHelper::Set3DPreviewFormat method

HRESULT IDeckLinkMetalScreenPreviewHelper::Set3DPreviewFormat(BMD3DPreviewFormat previewFormat);

The Set3DPreviewFormat method is used to set the 3D preview format.

Parameters:

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

Return values:

• E_INVALIDARG – The preview format is invalid

• E_FAIL – Failure

• S_OK – Success