Edit

Share via

IMFCaptureEngine::Initialize method (mfcaptureengine.h)

  • Article

Initializes the capture engine.

Syntax

HRESULT Initialize(
  [in]           IMFCaptureEngineOnEventCallback *pEventCallback,
  [in, optional] IMFAttributes                   *pAttributes,
  [in, optional] IUnknown                        *pAudioSource,
  [in, optional] IUnknown                        *pVideoSource
);

Parameters

[in] pEventCallback

A pointer to the IMFCaptureEngineOnEventCallback interface. The caller must implement this interface. The capture engine uses this interface to send asynchronous events to the caller.

[in, optional] pAttributes

A pointer to the IMFAttributes interface. This parameter can be NULL.

You can use this parameter to configure the capture engine. Call MFCreateAttributes to create an attribute store, and then set any of the following attributes.

[in, optional] pAudioSource

An IUnknown pointer that specifies an audio-capture device. This parameter can be NULL.

If you set the MF_CAPTURE_ENGINE_USE_VIDEO_DEVICE_ONLY attribute to TRUE in pAttributes, the capture engine does not use an audio device, and the pAudioSource parameter is ignored.

Otherwise, if pAudioSource is NULL, the capture engine selects the microphone that is built into the video camera specified by pVideoSource. If the video camera does not have a microphone, the capture engine enumerates the audio-capture devices on the system and selects the first one.

To override the default audio device, set pAudioSource to an IMFMediaSource or IMFActivate pointer for the device. For more information, see Audio/Video Capture in Media Foundation.

[in, optional] pVideoSource

An IUnknown pointer that specifies a video-capture device. This parameter can be NULL.

If you set the MF_CAPTURE_ENGINE_USE_AUDIO_DEVICE_ONLY attribute to TRUE in pAttributes, the capture engine does not use a video device, and the pVideoSource parameter is ignored.

Otherwise, if pVideoSource is NULL, the capture engine enumerates the video-capture devices on the system and selects the first one.

To override the default video device, set pVideoSource to an IMFMediaSource or IMFActivate pointer for the device. For more information, see Enumerating Video Capture Devices.

Return value

This method can return one of these values.

Return code Description
S_OK
 Success.
MF_E_INVALIDREQUEST
 The Initialize method was already called.
MF_E_NO_CAPTURE_DEVICES_AVAILABLE
 No capture devices are available.
MF_E_UNSUPPORTED_CAPTURE_DEVICE_PRESENT
 An unsupported capture device is present on the system. This error will only be returned if NULL is specified for the pVideoSource parameter, indicating that the system should pick the capture device, and if no supported capture device has already been attached. It is recommended that apps show users a specific unsupported capture device message if this error is returned, rather than a general failure message.

Remarks

You must call this method once before using the capture engine. Calling the method a second time returns MF_E_INVALIDREQUEST.

This method is asynchronous. If the method returns a success code, the caller will receive an MF_CAPTURE_ENGINE_INITIALIZED event through the IMFCaptureEngineOnEventCallback::OnEvent method. The operation can fail asynchronously after the method succeeds. If so, the error code is conveyed through the OnEvent method.

Requirements

Requirement Value
Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Target Platform Windows
Header mfcaptureengine.h

See also

IMFCaptureEngine