MFCreateVirtualCamera function (mfvirtualcamera.h)
Creates a virtual camera object which can be used by the caller to register, unregister, or remove the virtual camera from the system.
Syntax
HRESULT MFCreateVirtualCamera(
MFVirtualCameraType type,
MFVirtualCameraLifetime lifetime,
MFVirtualCameraAccess access,
LPCWSTR friendlyName,
LPCWSTR sourceId,
const GUID *categories,
ULONG categoryCount,
IMFVirtualCamera **virtualCamera
);
Parameters
type
A member of the MFVirtualCameraType enumeration specifying the virtual camera type. In the current release, only MFVirtualCameraType_SoftwareCameraSource is supported.
lifetime
A member of the MFVirtualCameraLifetime enumeration specifying the lifetime of the camera. If MFVirtualCameraLifetime_Session is specified, when the returned IMFVirtualCamera object is disposed or IMFVirtualCamera::Shutdown is called, the virtual camera will no longer be enumerable or activatable on the device. If you want the virtual camera to persist across sessions and/or across reboots, you must specify the value MFVirtualCameraLifetime_System.
access
A member of the MFVirtualCameraAccess enumeration specifying the access scope of the created virtual camera. If MFVirtualCameraAccess_CurrentUser is specified, the virtual camera is only created for the user account that called the MFCreateVirtualCamera. If MFVirtualCameraAccess_AllUsers is specified, all users on the device will be able to enumerate or activate the virtual camera. To create a virtual camera with MFVirtualCameraAccess_AllUsers, the caller of MFCreateVirtualCamera must have administrator permissions.
friendlyName
A null-terminated, user-readable Unicode string friendly name for the created virtual camera. The pipeline will automatically append “Windows Virtual Camera” to the provided friendly name to ensure end users can distinguish virtual cameras from physical cameras based on the friendly name. This parameter must not be nullptr.
sourceId
The unique CLSID of the custom media source to be activated for this virtual camera. The string must be in the “{CLSID}” format. This parameter must not be nullptr.
categories
An optional list of device interface categories under which the virtual camera is registered. If a non-administrator user is invoking MFCreateVirtualCamera, the categories must be a subset of the following values:
If nullptr is specified, the virtual camera is registered under the KSCATEGORY_VIDEO_CAMERA, KSCATEGORY_VIDEO and KSCATEGORY_CAPTURE categories.
categoryCount
The number of categories provided in the categories parameter. If categories is nullptr, categoryCount must be 0.
virtualCamera
Output parameter that receives the newly created IMFVirtualCamera. This parameter must not be nullptr.
Return value
Returns an HRESULT value, including but not limited to the following values:
Error code | Description |
---|---|
S_OK | Succeeded |
E_INVALIDARG | An input parameter is invalid. |
E_POINTER | The virtualCamera parameter is nullptr. |
E_ACCESSDENIED | Privacy control is set to deny access to the camera for the app, user, or system. Or the caller is not an administrator and the parameters provided are only valid for administrator access. |
Remarks
The virtual camera created by MFCreateVirtualCamera is keyed off the parameters passed in to this API. By keeping the same parameters, applications can re-open the same virtual camera. When called for the first time, the resulting IMFVirtualCamera contains a set of configuration information which may be modified or updated by the caller to create a new instance of a virtual camera. If the same parameters are used for this function on subsequent calls, the resulting IMFVirtualCamera will open the existing virtual camera when the IMFVirtualCamera::Start or IMFVirtualCamera::Stop method is called. Calling IMFVirtualCamera::Remove will remove the existing virtual camera. If MFVirtualCameraAccess_CurrentUser is specified for the access parameter, each user account gets a unique virtual camera.
UWP and Packaged Application must declare the webcam device capability in their manifest in order to use this API. This API is also subject to the webcam privacy control so when privacy is set to deny access, this API will result in an E_ACCESSDENIED failure.
Note
UWP and Packaged Apps must not invoke MFCreateVirtualCamera on their UI thread. Doing so will potentially trigger a deadlock as the Capability Access Manager check for the webcam access consent dialog will be blocked.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows Build 22000 |
Header | mfvirtualcamera.h |
Library | mfsensorgroup.lib |
DLL | mfsensorgroup.dll |
See also
IMFVirtualCamera MFVirtualCameraType MFVirtualCameraLifetime MFVirtualCameraAccess