ホーム › Media.MediaFoundation › MFCreateVirtualCamera

MFCreateVirtualCamera

関数

仮想カメラを作成して登録する。

シグネチャ

// MFSENSORGROUP.dll
#include <windows.h>

HRESULT MFCreateVirtualCamera(
    MFVirtualCameraType type,
    MFVirtualCameraLifetime lifetime,
    MFVirtualCameraAccess access,
    LPCWSTR friendlyName,
    LPCWSTR sourceId,
    const GUID* categories,   // optional
    DWORD categoryCount,
    IMFVirtualCamera** virtualCamera
);

パラメーター

名前	型	方向	説明
type	MFVirtualCameraType	in	仮想カメラの種類を指定する MFVirtualCameraType 列挙型のメンバー。現在のリリースでは、MFVirtualCameraType_SoftwareCameraSource のみがサポートされています。
lifetime	MFVirtualCameraLifetime	in	カメラの有効期間を指定する MFVirtualCameraLifetime 列挙型のメンバー。MFVirtualCameraLifetime_Session を指定した場合、返された IMFVirtualCamera オブジェクトが破棄されるか IMFVirtualCamera::Shutdown が呼び出されると、仮想カメラはデバイス上で列挙またはアクティブ化できなくなります。仮想カメラをセッション間および/または再起動をまたいで保持したい場合は、MFVirtualCameraLifetime_System の値を指定する必要があります。
access	MFVirtualCameraAccess	in	作成する仮想カメラのアクセススコープを指定する MFVirtualCameraAccess 列挙型のメンバー。MFVirtualCameraAccess_CurrentUser を指定した場合、仮想カメラは MFCreateVirtualCamera を呼び出したユーザーアカウントに対してのみ作成されます。MFVirtualCameraAccess_AllUsers を指定した場合、デバイス上のすべてのユーザーが仮想カメラを列挙またはアクティブ化できます。MFVirtualCameraAccess_AllUsers で仮想カメラを作成するには、MFCreateVirtualCamera の呼び出し元が管理者権限を持っている必要があります。
friendlyName	LPCWSTR	in	作成する仮想カメラのための、null 終端されたユーザーが読める Unicode 文字列のフレンドリ名。パイプラインは、エンドユーザーがフレンドリ名に基づいて仮想カメラを物理カメラと区別できるようにするため、指定されたフレンドリ名に自動的に「Windows Virtual Camera」を付加します。このパラメーターは nullptr であってはなりません。
sourceId	LPCWSTR	in	この仮想カメラに対してアクティブ化される、カスタムメディアソースの一意な CLSID。文字列は「{CLSID}」形式である必要があります。このパラメーターは nullptr であってはなりません。
categories	GUID*	inoptional	仮想カメラを登録するデバイスインターフェイスカテゴリのオプションのリスト。管理者以外のユーザーが MFCreateVirtualCamera を呼び出す場合、カテゴリは以下の値のサブセットである必要があります。 KSCATEGORY_VIDEO_CAMERA KSCATEGORY_VIDEO KSCATEGORY_CAPTURE KSCATEGORY_SENSOR_CAMERA nullptr を指定した場合、仮想カメラは KSCATEGORY_VIDEO_CAMERA、KSCATEGORY_VIDEO、および KSCATEGORY_CAPTURE カテゴリの下に登録されます。
categoryCount	DWORD	in	categories パラメーターで指定されたカテゴリの数。categories が nullptr の場合、categoryCount は 0 でなければなりません。
virtualCamera	IMFVirtualCamera**	out	新しく作成された IMFVirtualCamera を受け取る出力パラメーター。このパラメーターは nullptr であってはなりません。

戻り値の型: HRESULT

公式ドキュメント

仮想カメラオブジェクトを作成します。このオブジェクトは、呼び出し元が仮想カメラをシステムに登録、登録解除、または削除するために使用できます。

戻り値

HRESULT 値を返します。次の値を含みますが、これらに限定されません。

エラーコード	説明
S_OK	成功しました
E_INVALIDARG	入力パラメーターが無効です。
E_POINTER	virtualCamera パラメーターが nullptr です。
E_ACCESSDENIED	プライバシー制御により、アプリ、ユーザー、またはシステムに対するカメラへのアクセスが拒否されるように設定されています。または、呼び出し元が管理者ではなく、指定されたパラメーターが管理者アクセスでのみ有効です。

解説(Remarks)

MFCreateVirtualCamera によって作成される仮想カメラは、この API に渡されたパラメーターをキーとして識別されます。同じパラメーターを保持することで、アプリケーションは同じ仮想カメラを再び開くことができます。初めて呼び出されたとき、結果として得られる IMFVirtualCamera には一連の構成情報が含まれ、呼び出し元はこれを変更または更新して仮想カメラの新しいインスタンスを作成できます。以降の呼び出しでこの関数に同じパラメーターを使用した場合、結果として得られる IMFVirtualCamera は、IMFVirtualCamera::Start または IMFVirtualCamera::Stop メソッドが呼び出されたときに既存の仮想カメラを開きます。IMFVirtualCamera::Remove を呼び出すと、既存の仮想カメラが削除されます。access パラメーターに MFVirtualCameraAccess_CurrentUser を指定した場合、各ユーザーアカウントは一意の仮想カメラを取得します。

UWP およびパッケージ化されたアプリケーションは、この API を使用するために、マニフェストで webcam デバイス機能を宣言する必要があります。この API は webcam プライバシー制御の対象でもあるため、プライバシーがアクセス拒否に設定されている場合、この API は E_ACCESSDENIED エラーになります。

メモ

UWP およびパッケージ化されたアプリは、UI スレッド上で MFCreateVirtualCamera を呼び出してはなりません。これを行うと、webcam アクセス同意ダイアログに関する Capability Access Manager のチェックがブロックされるため、デッドロックを引き起こす可能性があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// MFSENSORGROUP.dll
#include <windows.h>

HRESULT MFCreateVirtualCamera(
    MFVirtualCameraType type,
    MFVirtualCameraLifetime lifetime,
    MFVirtualCameraAccess access,
    LPCWSTR friendlyName,
    LPCWSTR sourceId,
    const GUID* categories,   // optional
    DWORD categoryCount,
    IMFVirtualCamera** virtualCamera
);

[DllImport("MFSENSORGROUP.dll", ExactSpelling = true)]
static extern int MFCreateVirtualCamera(
    int type,   // MFVirtualCameraType
    int lifetime,   // MFVirtualCameraLifetime
    int access,   // MFVirtualCameraAccess
    [MarshalAs(UnmanagedType.LPWStr)] string friendlyName,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string sourceId,   // LPCWSTR
    IntPtr categories,   // GUID* optional
    uint categoryCount,   // DWORD
    IntPtr virtualCamera   // IMFVirtualCamera** out
);

<DllImport("MFSENSORGROUP.dll", ExactSpelling:=True)>
Public Shared Function MFCreateVirtualCamera(
    type As Integer,   ' MFVirtualCameraType
    lifetime As Integer,   ' MFVirtualCameraLifetime
    access As Integer,   ' MFVirtualCameraAccess
    <MarshalAs(UnmanagedType.LPWStr)> friendlyName As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> sourceId As String,   ' LPCWSTR
    categories As IntPtr,   ' GUID* optional
    categoryCount As UInteger,   ' DWORD
    virtualCamera As IntPtr   ' IMFVirtualCamera** out
) As Integer
End Function

' type : MFVirtualCameraType
' lifetime : MFVirtualCameraLifetime
' access : MFVirtualCameraAccess
' friendlyName : LPCWSTR
' sourceId : LPCWSTR
' categories : GUID* optional
' categoryCount : DWORD
' virtualCamera : IMFVirtualCamera** out
Declare PtrSafe Function MFCreateVirtualCamera Lib "mfsensorgroup" ( _
    ByVal type As Long, _
    ByVal lifetime As Long, _
    ByVal access As Long, _
    ByVal friendlyName As LongPtr, _
    ByVal sourceId As LongPtr, _
    ByVal categories As LongPtr, _
    ByVal categoryCount As Long, _
    ByVal virtualCamera As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

MFCreateVirtualCamera = ctypes.windll.mfsensorgroup.MFCreateVirtualCamera
MFCreateVirtualCamera.restype = ctypes.c_int
MFCreateVirtualCamera.argtypes = [
    ctypes.c_int,  # type : MFVirtualCameraType
    ctypes.c_int,  # lifetime : MFVirtualCameraLifetime
    ctypes.c_int,  # access : MFVirtualCameraAccess
    wintypes.LPCWSTR,  # friendlyName : LPCWSTR
    wintypes.LPCWSTR,  # sourceId : LPCWSTR
    ctypes.c_void_p,  # categories : GUID* optional
    wintypes.DWORD,  # categoryCount : DWORD
    ctypes.c_void_p,  # virtualCamera : IMFVirtualCamera** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('MFSENSORGROUP.dll')
MFCreateVirtualCamera = Fiddle::Function.new(
  lib['MFCreateVirtualCamera'],
  [
    Fiddle::TYPE_INT,  # type : MFVirtualCameraType
    Fiddle::TYPE_INT,  # lifetime : MFVirtualCameraLifetime
    Fiddle::TYPE_INT,  # access : MFVirtualCameraAccess
    Fiddle::TYPE_VOIDP,  # friendlyName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # sourceId : LPCWSTR
    Fiddle::TYPE_VOIDP,  # categories : GUID* optional
    -Fiddle::TYPE_INT,  # categoryCount : DWORD
    Fiddle::TYPE_VOIDP,  # virtualCamera : IMFVirtualCamera** out
  ],
  Fiddle::TYPE_INT)

#[link(name = "mfsensorgroup")]
extern "system" {
    fn MFCreateVirtualCamera(
        type: i32,  // MFVirtualCameraType
        lifetime: i32,  // MFVirtualCameraLifetime
        access: i32,  // MFVirtualCameraAccess
        friendlyName: *const u16,  // LPCWSTR
        sourceId: *const u16,  // LPCWSTR
        categories: *const GUID,  // GUID* optional
        categoryCount: u32,  // DWORD
        virtualCamera: *mut *mut core::ffi::c_void  // IMFVirtualCamera** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("MFSENSORGROUP.dll")]
public static extern int MFCreateVirtualCamera(int type, int lifetime, int access, [MarshalAs(UnmanagedType.LPWStr)] string friendlyName, [MarshalAs(UnmanagedType.LPWStr)] string sourceId, IntPtr categories, uint categoryCount, IntPtr virtualCamera);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MFSENSORGROUP_MFCreateVirtualCamera' -Namespace Win32 -PassThru
# $api::MFCreateVirtualCamera(type, lifetime, access, friendlyName, sourceId, categories, categoryCount, virtualCamera)

#uselib "MFSENSORGROUP.dll"
#func global MFCreateVirtualCamera "MFCreateVirtualCamera" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; MFCreateVirtualCamera type, lifetime, access, friendlyName, sourceId, varptr(categories), categoryCount, virtualCamera   ; 戻り値は stat
; type : MFVirtualCameraType -> "sptr"
; lifetime : MFVirtualCameraLifetime -> "sptr"
; access : MFVirtualCameraAccess -> "sptr"
; friendlyName : LPCWSTR -> "sptr"
; sourceId : LPCWSTR -> "sptr"
; categories : GUID* optional -> "sptr"
; categoryCount : DWORD -> "sptr"
; virtualCamera : IMFVirtualCamera** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "MFSENSORGROUP.dll"
#cfunc global MFCreateVirtualCamera "MFCreateVirtualCamera" int, int, int, wstr, wstr, var, int, sptr
; res = MFCreateVirtualCamera(type, lifetime, access, friendlyName, sourceId, categories, categoryCount, virtualCamera)
; type : MFVirtualCameraType -> "int"
; lifetime : MFVirtualCameraLifetime -> "int"
; access : MFVirtualCameraAccess -> "int"
; friendlyName : LPCWSTR -> "wstr"
; sourceId : LPCWSTR -> "wstr"
; categories : GUID* optional -> "var"
; categoryCount : DWORD -> "int"
; virtualCamera : IMFVirtualCamera** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "MFSENSORGROUP.dll"
#cfunc global MFCreateVirtualCamera "MFCreateVirtualCamera" int, int, int, wstr, wstr, sptr, int, sptr
; res = MFCreateVirtualCamera(type, lifetime, access, friendlyName, sourceId, varptr(categories), categoryCount, virtualCamera)
; type : MFVirtualCameraType -> "int"
; lifetime : MFVirtualCameraLifetime -> "int"
; access : MFVirtualCameraAccess -> "int"
; friendlyName : LPCWSTR -> "wstr"
; sourceId : LPCWSTR -> "wstr"
; categories : GUID* optional -> "sptr"
; categoryCount : DWORD -> "int"
; virtualCamera : IMFVirtualCamera** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。