ホーム › Media.MediaFoundation › IMFVirtualCamera

IMFVirtualCamera

COM

IID1c08a864-ef6c-4c75-af59-5f2d68da9563継承元IMFAttributes自前メソッド開始 vtbl33

公式ドキュメント

Media Foundation フレームサーバーパイプラインに接続可能な仮想カメラを表します。

解説(Remarks)

MFCreateVirtualCamera を呼び出して IMFVirtualCamera のインスタンスを作成します。MFCreateVirtualCamera からこのインターフェイスが初めて返されたとき、このインターフェイスは一連の構成オプションを表します。呼び出し元は、カメラを開始する前に仮想カメラのさまざまな設定を構成する責任があります。IMFVirtualCamera::Start メソッドを呼び出すことで、そのカメラをデバイス上で検出および有効化できるようになります。

メソッド 11

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 33 HRESULT AddDeviceSourceInfo(LPWSTR DeviceSourceInfo)

指定されたデバイスシンボリック名で指定された物理カメラに対して、仮想カメラが排他制御を必要とすることをパイプラインに通知します。

DeviceSourceInfo

LPWSTR

物理カメラのシンボリック名を含む LPCWSTR。この値は、MFEnumDeviceSources や DeviceInformation などの標準的な Windows 列挙 API を通じて列挙されます。

戻り値

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

Error code	Description
S_OK	成功しました。
E_INVALIDARG	入力パラメーターが無効です。

解説(Remarks)

この関数は、仮想カメラが有効化されたときに、Windows Camera Frame Server サービスが物理カメラへのアクセスを調停できるようにします。

仮想カメラが複数の物理カメラへの排他アクセスを必要とする場合、この API を繰り返し呼び出すことができます。

メモ

仮想カメラが有効化されると、この API を使用して仮想カメラに追加されたすべての物理カメラは使用中としてマークされます。そのため、それらの物理カメラに非共有モードでアクセスしようとすると、共有違反が発生します。

vtbl 34 HRESULT AddProperty(DEVPROPKEY* pKey, DEVPROPTYPE Type, BYTE* pbData, DWORD cbData)

仮想カメラにカスタムデバイスインターフェイスプロパティを追加します。

pKey	DEVPROPKEY*	in	仮想カメラのデバイスインターフェイスに追加する DEVPROPKEY へのポインター。詳細については、Unified Device Property Model を参照してください。
Type	DEVPROPTYPE	in	指定された pKey のプロパティ型。DEVPROP_TYPE_NULL 型および DEVPROP_TYPE_EMPTY 型はサポートされていません。
pbData	BYTE*	in	プロパティデータへのポインター。
cbData	DWORD	in	data が指すバッファーに含まれるサイズ (バイト単位)。

戻り値

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

Error code	Description
S_OK	成功しました。
E_INVALIDARG	入力パラメーターが無効です。
E_ACCESSDENIED	呼び出し元にプロパティを追加するための十分な権限がありません。

解説(Remarks)

呼び出し元は、この API を使用するために管理者レベルの権限を持っている必要があります。UWP アプリおよびパッケージ化されたアプリには、このメソッドを呼び出す権限がありません。

既知の Windows デバイスプロパティを追加すると予期しない影響が生じる可能性があるため、呼び出し元は注意して追加する必要があります。

vtbl 35 HRESULT AddRegistryEntry(LPWSTR EntryName, LPWSTR SubkeyPath, DWORD dwRegType, BYTE* pbData, DWORD cbData)

デバイスインターフェイスレジストリキーにカスタムレジストリエントリを追加します。

EntryName	LPWSTR	in	レジストリエントリ名を表す null 終端の Unicode 文字列。
SubkeyPath	LPWSTR	inoptional	デバイスインターフェイスレジストリノード配下のサブキーを表す、省略可能な null 終端の Unicode 文字列。
dwRegType	DWORD	in	レジストリエントリのデータ型。REG_NONE 型はサポートされていません。詳細については、Registry Value Types を参照してください。
pbData	BYTE*	in	レジストリエントリのデータへのポインター。
cbData	DWORD	in	pbData が指すバッファー内のデータのサイズ (バイト単位)。

戻り値

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

Error code	Description
S_OK	成功しました。
E_INVALIDARG	入力パラメーターが無効です。
E_ACCESSDENIED	呼び出し元にプロパティを追加するための十分な権限がありません。

解説(Remarks)

vtbl 36 HRESULT Start(IMFAsyncCallback* pCallback)

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

pCallback

IMFAsyncCallback*

inoptional

パイプラインが仮想カメラの状態を呼び出し元に通知するために使用する IMFAsyncCallback オブジェクトへの省略可能なポインター。コールバックが指定されている場合、IMFMediaEvent を伴って呼び出されることがあります。呼び出されたとき、IMFMediaEvent::GetType メソッドは MEExtendedType または MEError を返します。MEExtendedType が返された場合、IMFMediaEvent::GetExtendedType メソッドは次のイベント型のいずれかを返すことがあります。

Extended event type	Description
MF_FRAMESERVER_VCAMEVENT_EXTENDED_SOURCE_INITIALIZE	仮想カメラを表すカスタムメディアソースがアプリケーションによって初期化されました。
MF_FRAMESERVER_VCAMEVENT_EXTENDED_SOURCE_START	仮想カメラのカスタムメディアソース上のストリーム (1 つまたは複数) がアプリケーションによって開始されました。
MF_FRAMESERVER_VCAMEVENT_EXTENDED_SOURCE_STOP	仮想カメラのカスタムメディアソース上のすべてのストリームがアプリケーションによって停止されました。
MF_FRAMESERVER_VCAMEVENT_EXTENDED_SOURCE_UNINITIALIZE	仮想カメラのカスタムメディアソースが初期化解除されました。
MF_FRAMESERVER_VCAMEVENT_EXTENDED_PIPELINE_SHUTDOWN	仮想カメラのパイプラインがシャットダウンされました。
MF_FRAMESERVER_VCAMEVENT_EXTENDED_CUSTOM_EVENT	仮想カメラのカスタムメディアソースによってカスタムイベントが生成されました。IMFMediaEvent のスキーマはベンダー固有です。

コールバックは、IMFVirtualCamera::Start が正常に返された後、いつでも呼び出される可能性があります。

戻り値

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

Error code	Description
S_OK	成功しました。
E_INVALIDARG	入力パラメーターが無効です。

解説(Remarks)

Start メソッドの呼び出しが成功するまで、IMFVirtualCamera は仮想カメラの構成情報を表しているにすぎず、基になる仮想カメラはまだ存在しません。ただし、MFCreateVirtualCamera が既存の仮想カメラを再度開いている場合を除きます。 Start が正常に呼び出されると、IMFVirtualCamera が継承する IMFAttributes に、新たに作成された仮想カメラのシンボリックリンク名 MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK が格納されます。

IMFVirtualCamera::Start の呼び出しが成功して既に開始されている IMFVirtualCamera を指定して、以前の呼び出しと同じパラメーターで MFCreateVirtualCamera が呼び出された場合、その結果の IMFVirtualCamera は既に有効な状態にあり、以降の IMFVirtualCamera::Start の呼び出しは新しいコールバックを登録するために使用できます。

vtbl 37 HRESULT Stop()

登録された仮想カメラを無効にし、アプリが仮想カメラを列挙または有効化できないようにブロックします。

戻り値

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

Error code	Description
S_OK	成功しました。
E_ACCESSDENIED	仮想カメラがシステム全体のカメラであり、呼び出し元にそれを削除する権限がありません。

解説(Remarks)

仮想カメラの使用中に Stop を呼び出すと、それらのアプリケーションは MF_E_VIDEO_RECORDING_DEVICE_INVALIDATED エラーを受け取ります。

vtbl 38 HRESULT Remove()

仮想カメラを無効にし、システムから登録解除します。

戻り値

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

Error code	Description
S_OK	成功しました。
E_ACCESSDENIED	仮想カメラがシステム全体のカメラであり、呼び出し元にそれを削除する権限がありません。

解説(Remarks)

ライフタイム中に仮想カメラを作成するアプリケーションは、アプリケーションがアンインストールされるときにそれらの仮想カメラが削除されるようにする必要があります。

仮想カメラの使用中に Remove を呼び出すと、それらのアプリケーションは MF_E_VIDEO_RECORDING_DEVICE_INVALIDATED エラーを受け取ります。

vtbl 39 HRESULT GetMediaSource(IMFMediaSource** ppMediaSource)

仮想カメラからメディアデータを提供する IMFMediaSource を取得します。

ppMediaSource

IMFMediaSource**

out

仮想カメラからの共有クライアントの IMFMediaSource。

戻り値

Error code	Description
S_OK	成功しました。

解説(Remarks)

GetMediaSource は、IMFVirtualCamera::Start が正常に呼び出された後でなければ呼び出せません。ppMediaSource パラメーターで返される IMFMediaSource は、機能が制限されたメディアソースです。内部的には共有クライアントとしてマークされています。このメディアソースは、仮想カメラの有効化および構成の処理中に、アプリがローカルプレビューとして使用することを意図しています。

完全な機能を備えた IMFMediaSource が必要な場合、アプリは IMFVirtualCamera::Start の呼び出し後に IMFAttributes で返されたシンボリックリンク名を使用して MFCreateDeviceSource を呼び出す必要があります。ただし、そうすると排他制御のメディアソースが作成され、それが有効化されると他のすべてのアプリが仮想カメラを使用できなくなります。

このメソッドで取得される IMFMediaSource の有効期間は、それが取得された元の IMFVirtualCamera の有効期間に直接結び付けられます。IMFVirtualCamera が破棄されるか IMFVirtualCamera::Shutdown が呼び出されると、このメソッドで取得された IMFMediaSource もシャットダウンされます。

vtbl 40 HRESULT SendCameraProperty(GUID* propertySet, DWORD propertyId, DWORD propertyFlags, void* propertyPayload, DWORD propertyPayloadLength, void* data, DWORD dataLength, DWORD* dataWritten)

内部の IKsControl::KsProperty メソッドのラッパーです。

propertySet	GUID*	in	KSPROPERTY.Set フィールドを表す GUID。
propertyId	DWORD	in	KSPROPERTY.Id フィールドを表す ULONG。
propertyFlags	DWORD	in	KSPROPERTY.Flags フィールドを表す、ビット単位の論理和を取ったフラグのセット。
propertyPayload	void*	inoutoptional	KSPROPERTY 構造体の末尾に追加される拡張データ。指定されたプロパティペイロードは、仮想カメラのカスタムメディアソースに送信される前に KSPROPERTY 構造体の末尾に追加されます。
propertyPayloadLength	DWORD	in	propertyPayload が指すバッファーのサイズ (バイト単位)。
data	void*	inoutoptional	プロパティのペイロード用のバイトバッファー。
dataLength	DWORD	in	data が指すバッファーのサイズ (バイト単位)。
dataWritten	DWORD*	out	data バッファーに書き込まれたデータ量を示す出力パラメーター。この値は、commandFlags に GET またはクエリ操作が含まれている場合にのみ有効です。

戻り値

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

Error code	Description
S_OK	成功しました。

vtbl 41 HRESULT CreateSyncEvent(GUID* kseventSet, DWORD kseventId, DWORD kseventFlags, HANDLE eventHandle, IMFCameraSyncObject** cameraSyncObject)

イベントを有効または無効にする IKsControl::KsEvent メソッドのラッパーです。

kseventSet	GUID*	in	KSEVENT.Set フィールドを表す GUID。
kseventId	DWORD	in	KSEVENT.Id フィールドを表す ULONG。
kseventFlags	DWORD	in	KSEVENT.Flags フィールドを表す、ビット単位の論理和を取ったフラグのセット。
eventHandle	HANDLE	in	KSEVENTDATA.EventHandle.Event フィールドを表すハンドル。
cameraSyncObject	IMFCameraSyncObject**	out	IMFSyncObject インターフェイスを受け取る出力パラメーター。呼び出し元はこのオブジェクトを解放する責任があります。

戻り値

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

Error code	Description
S_OK	成功しました。

解説(Remarks)

このメソッドを使用すると、呼び出し元は、同期のために呼び出し元と仮想カメラの間にイベントオブジェクトを作成できます。この API が呼び出されると、仮想カメラの実装は IKsControl::KsEvent への呼び出しを受け取ります。結果として得られる IMFCameraSyncObject は、仮想カメラからのイベントでブロックするために使用できます。

IMFCameraSyncObject が取得されると、呼び出し元は IMFCameraSyncObject::WaitOnSignal メソッドを使用するか、CreateSyncObject メソッドに指定された HANDLE に対して WaitForSingleObject または WaitForMultipleObjects を呼び出すかを選択できます。イベントのシグナルはドライバーによって一度しか設定されない可能性があるため、呼び出し元は両方を待機してはなりません。

呼び出し元は、待機操作が成功したかどうかにかかわらず、同期オブジェクトが不要になったら IMFCameraSyncObject::Shutdown を呼び出す必要があります。

vtbl 42 HRESULT CreateSyncSemaphore(GUID* kseventSet, DWORD kseventId, DWORD kseventFlags, HANDLE semaphoreHandle, INT semaphoreAdjustment, IMFCameraSyncObject** cameraSyncObject)

セマフォを有効または無効にする IKsControl::KsEvent メソッドのラッパーです。

kseventSet	GUID*	in	KSEVENT.Set フィールドを表す GUID。
kseventId	DWORD	in	KSEVENT.Id フィールドを表す ULONG。
kseventFlags	DWORD	in	KSEVENT.Flags フィールドを表す、ビット単位の論理和を取ったフラグのセット。
semaphoreHandle	HANDLE	in	KSEVENTDATA.SemaphoreHandle.Semaphore フィールドを表すハンドル。
semaphoreAdjustment	INT	in	KSEVENTDATA.SemaphoreHandle.Adjustment フィールドを表す調整値。
cameraSyncObject	IMFCameraSyncObject**	out	IMFSyncObject インターフェイスを受け取る出力パラメーター。呼び出し元はこのオブジェクトを解放する責任があります。

戻り値

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

Error code	Description
S_OK	成功しました。

解説(Remarks)

このメソッドを使用すると、呼び出し元は、同期のために呼び出し元と仮想カメラの間にセマフォオブジェクトを作成できます。この API が呼び出されると、仮想カメラの実装は IKsControl::KsEvent への呼び出しを受け取ります。結果として得られる IMFCameraSyncObject は、仮想カメラからのイベントでブロックするために使用できます。

呼び出し元は、待機操作が成功したかどうかにかかわらず、同期オブジェクトが不要になったら IMFCameraSyncObject::Shutdown を呼び出す必要があります。

vtbl 43 HRESULT Shutdown()

仮想カメラのすべての内部リソースを解放します。

戻り値

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

Error code	Description
S_OK	成功しました。

解説(Remarks)

Shutdown が呼び出されると、IMFVirtualCamera API を通じて作成されたすべてのオブジェクトもシャットダウンされます。これには、IMFVirtualCamera::CreateSyncEvent または CreateSyncSemaphore の呼び出しを通じて取得された IMFCameraSyncObject オブジェクトや、IMFVirtualCamera::GetMediaSource の呼び出しを通じて取得された IMFMediaSource オブジェクトが含まれます。Shutdown が呼び出された後に IMFVirtualCamera から取得したオブジェクトを使用しようとすると、MF_E_SHUTDOWN エラーが発生します。

ライフタイム値 MFVirtualCameraLifeTime_Session で作成された仮想カメラの場合、Shutdown が呼び出されると、その仮想カメラはシステムから削除されます。仮想カメラを使用しているアプリケーションは、デバイス無効化エラー MF_E_VIDEO_RECORDING_DEVICE_INVALIDATED を受け取ります。

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

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IMFVirtualCamera "{1C08A864-EF6C-4C75-AF59-5F2D68DA9563}"
#usecom global IMFVirtualCamera IID_IMFVirtualCamera "{}"
#comfunc global IMFVirtualCamera_AddDeviceSourceInfo  33 wstr
#comfunc global IMFVirtualCamera_AddProperty          34 var,int,var,int
#comfunc global IMFVirtualCamera_AddRegistryEntry     35 wstr,wstr,int,var,int
#comfunc global IMFVirtualCamera_Start                36 sptr
#comfunc global IMFVirtualCamera_Stop                 37
#comfunc global IMFVirtualCamera_Remove               38
#comfunc global IMFVirtualCamera_GetMediaSource       39 sptr
#comfunc global IMFVirtualCamera_SendCameraProperty   40 var,int,int,sptr,int,sptr,int,var
#comfunc global IMFVirtualCamera_CreateSyncEvent      41 var,int,int,sptr,sptr
#comfunc global IMFVirtualCamera_CreateSyncSemaphore  42 var,int,int,sptr,int,sptr
#comfunc global IMFVirtualCamera_Shutdown             43
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IMFVirtualCamera "{1C08A864-EF6C-4C75-AF59-5F2D68DA9563}"
#usecom global IMFVirtualCamera IID_IMFVirtualCamera "{}"
#comfunc global IMFVirtualCamera_AddDeviceSourceInfo  33 wstr
#comfunc global IMFVirtualCamera_AddProperty          34 sptr,int,sptr,int
#comfunc global IMFVirtualCamera_AddRegistryEntry     35 wstr,wstr,int,sptr,int
#comfunc global IMFVirtualCamera_Start                36 sptr
#comfunc global IMFVirtualCamera_Stop                 37
#comfunc global IMFVirtualCamera_Remove               38
#comfunc global IMFVirtualCamera_GetMediaSource       39 sptr
#comfunc global IMFVirtualCamera_SendCameraProperty   40 sptr,int,int,sptr,int,sptr,int,sptr
#comfunc global IMFVirtualCamera_CreateSyncEvent      41 sptr,int,int,sptr,sptr
#comfunc global IMFVirtualCamera_CreateSyncSemaphore  42 sptr,int,int,sptr,int,sptr
#comfunc global IMFVirtualCamera_Shutdown             43
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。