IMFMediaEngineClassFactory::CreateInstance method (mfmediaengine.h)

Article
10/13/2021

Creates a new instance of the Media Engine.

Syntax

HRESULT CreateInstance(
  [in]  DWORD          dwFlags,
  [in]  IMFAttributes  *pAttr,
  [out] IMFMediaEngine **ppPlayer
);

Parameters

[in] dwFlags

A bitwise OR of zero or more flags from the MF_MEDIA_ENGINE_CREATEFLAGS enumeration.

[in] pAttr

A pointer to the IMFAttributes interface of an attribute store.

This parameter specifies configuration attributes for the Media Engine. Call MFCreateAttributes to create the attribute store. Then, set one or more attributes from the list of Media Engine Attributes. For details, see Remarks.

[out] ppPlayer

Receives a pointer to the IMFMediaEngine interface. The caller must release the interface.

Return value

This method can return one of these values.

Return code	Description
S_OK	Success.
MF_E_ATTRIBUTENOTFOUND	A required attribute was missing from pAttr, or an invalid combination of attributes was used.

Remarks

Before calling this method, call MFStartup.

The Media Engine supports three distinct modes:

Mode	Description
Frame-server mode	In this mode, the Media Engine delivers uncompressed video frames to the application. The application is responsible for displaying each frame, using Microsoft Direct3D or any other rendering technique. The Media Engine renders the audio; the application is not responsible for audio rendering. Frame-server mode is the default mode.
Rendering mode	In this mode, the Media Engine renders both audio and video. The video is rendered to a window or Microsoft DirectComposition visual provided by the application. To enable rendering mode, set either the MF_MEDIA_ENGINE_PLAYBACK_HWND attribute or the MF_MEDIA_ENGINE_PLAYBACK_VISUAL attribute.
Audio mode	In this mode, the Media Engine renders audio only, with no video. To enable audio mode, set the MF_MEDIA_ENGINE_AUDIOONLY flag in the dwFlags parameter.

Mode

Description

Frame-server mode

In this mode, the Media Engine delivers uncompressed video frames to the application. The application is responsible for displaying each frame, using Microsoft Direct3D or any other rendering technique.

The Media Engine renders the audio; the application is not responsible for audio rendering.

Frame-server mode is the default mode.

Rendering mode

In this mode, the Media Engine renders both audio and video. The video is rendered to a window or Microsoft DirectComposition visual provided by the application.

To enable rendering mode, set either the MF_MEDIA_ENGINE_PLAYBACK_HWND attribute or the MF_MEDIA_ENGINE_PLAYBACK_VISUAL attribute.

Audio mode

In this mode, the Media Engine renders audio only, with no video.

To enable audio mode, set the MF_MEDIA_ENGINE_AUDIOONLY flag in the dwFlags parameter.

Initialization Attributes

The following attributes are defined for the pAttr parameter. Some are required, and some are optional, depending on the mode you want.

Feature	Attributes	Frame Server Mode	Rendering Mode	Audio Mode
Event callback	MF_MEDIA_ENGINE_CALLBACK	Required.	Required.	Required.
Render target	One of the following: MF_MEDIA_ENGINE_PLAYBACK_HWND MF_MEDIA_ENGINE_PLAYBACK_VISUAL These attributes are mutually exclusive. Setting either of these attributes puts the Media Engine into rendering mode.	Do not set.	Required.	Do not set.
Direct3D format	MF_MEDIA_ENGINE_VIDEO_OUTPUT_FORMAT	Required.	Optional.	Do not set.
Microsoft DirectX Graphics Infrastructure (DXGI) device manager	MF_MEDIA_ENGINE_DXGI_MANAGER	Optional.	Optional.	Do not set.
Media Engine extensions	MF_MEDIA_ENGINE_EXTENSION	Optional.	Optional.	Optional.
Content protection	Any of the following: MF_MEDIA_ENGINE_OPM_HWND MF_MEDIA_ENGINE_CONTENT_PROTECTION_FLAGS MF_MEDIA_ENGINE_CONTENT_PROTECTION_MANAGER	Optional.	Optional.	Optional.
Audio playback	Any of the following: MF_MEDIA_ENGINE_AUDIO_CATEGORY MF_MEDIA_ENGINE_AUDIO_ENDPOINT_ROLE	Optional.	Optional.	Optional.

Windows Phone 8

This API is supported.

On the phone, the Media Engine only supports frame-server mode. Attempting to initialize the interface in either rendering mode or audio mode will fail.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	mfmediaengine.h