USB ビデオ クラス 1.5 仕様に対する Microsoft の拡張機能
1 概要
1.1 まとめ
USB Video クラス仕様 に対する Microsoft の拡張により、新しいコントロールと、明確に定義されたフレーム メタデータを標準形式で伝送する機能が可能になります。
1.2 アーキテクチャの決定
USB Video クラス (UVC) フレーム メタデータのサポートは、ISOCH および BULK エンドポイントで利用できます。 ただし、BULK エンドポイントの場合、メタデータ サイズは 240 バイトに制限されます (BULK エンドポイントではすべての ビデオ フレーム データが単一のビデオ フレーム パケットで転送されるため)。
UVC メタデータのサポートは、フレームベースのペイロードでのみ利用できます。
UVC メタデータのサポートは、Media Foundation (MF) キャプチャ パイプラインを通じてのみ利用できます。
UVC メタデータはオプトインです。 メタデータのサポートを必要とするすべての IHV/OEM は、カスタム INF ファイルを通じて有効にする必要があります。
UVC メタデータはシステム割り当てメモリのみをサポートします。 VRAM または DX サーフェスはサポートされません。
2 アーキテクチャの概要
2.1 説明
2.2.1 INF による機能検出
2.2.1.1 静止画像キャプチャ – 方法 2
一部の既存の UVC デバイスでは、 UVC 1.5 クラス仕様.pdf (USB ビデオ クラス仕様 Web サイトでダウンロード可能) セクション 2.4.2.4 (静止画像キャプチャ) で説明されている方法 2 をサポートしていない場合があります。
Windows 10 バージョン 1607 以前では、デバイスが UVC 1.5 仕様に従ってメソッド 2 のサポートをアドバタイズしていても、キャプチャ パイプラインはメソッド 2 を使用しませんでした。
Windows 10 バージョン 1703 では、この方法を使用するデバイスはカメラ ドライバーのカスタム INF ファイルを使用する必要がありますが、方法 2 の静止画キャプチャを有効にするには、特定のハードウェアにカスタム INF が必要です)。
注: カメラ ドライバーは、Windows USBVIDEO.SYSに基づくか、カスタム ドライバー バイナリに基づくことができます。
カスタム UVC ドライバーまたは受信トレイ UVC ドライバーに基づくカスタム INF ファイルには、次の AddReg エントリが含まれている必要があります。
EnableDependentStillPinCapture: REG_DWORD: 0x0 (無効) から0x1 (有効)
このエントリが有効 (0x1) に設定されている場合、キャプチャ パイプラインは静止画像キャプチャにメソッド 2 を使用します (UVC 1.5 仕様で指定されているように、ファームウェアもメソッド 2 のサポートをアドバタイズしていると仮定します)。
カスタム INF セクションの例を次に示します。
[USBVideo.NT.Interfaces]
AddInterface=%KSCATEGORY_CAPTURE%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_RENDER%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_VIDEO%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_RENDER_EXT%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_VIDEO_CAMERA%,GLOBAL,USBVideo.Interface
[USBVideo.Interface]
AddReg=USBVideo.Interface.AddReg
[USBVideo.Interface.AddReg]
HKR,,CLSID,,%ProxyVCap.CLSID%
HKR,,FriendlyName,,%USBVideo.DeviceDesc%
HKR,,RTCFlags,0x00010001,0x00000010
HKR,,EnableDependentStillPinCapture,0x00010001,0x00000001
2.2.2 拡張ユニットコントロール
新しいコントロールを有効にするための USB ビデオ クラス仕様 に対する Microsoft の拡張機能は、GUID MS_CAMERA_CONTROL_XU (Microsoft-XU と呼ばれます) によって識別される拡張ユニットを通じて行われます。
// {0F3F95DC-2632-4C4E-92C9-A04782F43BC8}
DEFINE_GUID(MS_CAMERA_CONTROL_XU,
0xf3f95dc, 0x2632, 0x4c4e, 0x92, 0xc9, 0xa0, 0x47, 0x82, 0xf4, 0x3b, 0xc8);
デバイス ファームウェアによって実装される Microsoft-XU には、次のサブセクションで定義される新しいコントロールが格納されます。 次の要求定義は、オーバーライド定義がそのコントロールに対して明示的に指定されていない限り、これらすべてのコントロールに適用されます。 D3、D4、GET_INFO などの定義については、 UVC 1.5 クラス仕様.pdf を参照してください。
GET_INFO要求は、AutoUpdate および非同期機能を持たないコントロールを報告する必要があります (たとえば、D3 ビットと D4 ビットは 0 に設定する)。
GET_LEN要求では、このコントロールのペイロードの最大長 (wLength) を報告する必要があります。
GET_RES要求は、 qwValue/dwValueの解決 (ステップ サイズ) を報告する必要があります。 その他のフィールドはすべて 0 に設定します。
GET_MIN要求は、 qwValue/dwValue でサポートされる最小値を報告する必要があります。 その他のフィールドはすべて 0 に設定します。
GET_MAX 要求は、 qwValue/dwValueでサポートされる最大値を報告する必要があります。 さらに、 bmControlFlagsでは、サポートされているすべてのフラグを 1 に設定する必要があります。 その他のフィールドはすべて 0 に設定します。
GET_DEF要求とGET_CUR要求は、フィールド qwValue/dwValue と bmControlFlags の既定の設定と現在の設定をそれぞれ報告する必要があります。 その他のフィールドはすべて 0 に設定します。
A SET_CUR 要求は、すべてのフィールドを設定した後、ホストによって発行されます。
次の表は、Microsoft-XU のコントロール セレクターをそれぞれの値と、拡張ユニット記述子の bmControls フィールドのビット位置にマップしたものです。
| コントロール セレクター | Value | ビット位置 (bmControls フィールド) |
|---|---|---|
| MSXU_CONTROL_UNDEFINED | 0x00 | NA |
| MSXU_CONTROL_FOCUS | 0x01 | D0 |
| MSXU_CONTROL_EXPOSURE | 0x02 | D1 |
| MSXU_CONTROL_EVCOMPENSATION | 0x03 | D2 |
| MSXU_CONTROL_WHITEBALANCE | 0x04 | D3 |
| 将来の使用のために予約済み | 0x05 | D4 |
| MSXU_CONTROL_FACE_AUTHENTICATION | 0x06 | D5 |
| MSXU_CONTROL_CAMERA_EXTRINSICS | 0x07 | D6 |
| MSXU_CONTROL_CAMERA_INTRINSICS | 0x08 | D7 |
| MSXU_CONTROL_METADATA | 0x09 | D8 |
| MSXU_CONTROL_IR_TORCH | 0x0A | D9 |
| MSXU_CONTROL_DIGITALWINDOW | 0X0B | D10 |
| MSXU_CONTROL_DIGITALWINDOW_CONFIG | 0X0C | D11 |
| MSXU_CONTROL_VIDEO_HDR | 0X0D | D12 |
| MSXU_CONTROL_FRAMERATE_THROTTLE | 0x0E | D13 |
| MSXU_CONTROL_FIELDOFVIEW2_CONFIG | 0x0F | D14 |
| MSXU_CONTROL_FIELDOFVIEW2 | 0x10 | D15 |
2.2.2.1 キャンセル可能なコントロール
ここでは、自動更新機能を使用して、Cancelable コントロールを定義します。
GET_INFO要求は、このようなコントロールを Autoupdate コントロール (たとえば、D3 ビットを 1 に設定する) と報告しますが、非同期コントロールとしては報告しません (たとえば、D4 ビットを 0 に設定する)。
このようなコントロールでは、Standard Edition T_CUR要求を発行して新しい値 (bmOperationFlags:D0 ビットが 0 に設定されているSET_CUR (NORMAL) 要求) を設定するか、前の SET_CUR (NORMAL) 要求 (bmOperationFlags:D0 ビットが 1 に設定されている SET_CUR (CANCEL) 要求) を取り消すことができます。 SET_CUR 要求は、要求を受信するとすぐにデバイスによって完了する必要があります (ハードウェアが構成されていない、または要求された新しい設定に収束していない場合でも)。 SET_CUR(NORMAL) リクエストごとに、デバイスは、新しい設定が適用されたとき、または SET_CUR(CANCEL) リクエストが到着したときに発生する、このコントロールに対応するコントロール チェンジ割り込みを生成します。 この割り込みが到着するまで、SET_CUR(NORMAL) リクエストは進行中であるとみなされます。 SET_CUR(NORMAL) 要求が進行中の場合、この特定のコントロールに対して追加の SET_CUR(NORMAL) 要求を実行すると、エラーが発生します。 SET_CUR(CANCEL) 要求は常に成功します。 キャンセルするものが何もない場合、デバイスは何も実行しません。
制御変更割り込みペイロードは、SET_CUR(NORMAL)で指定された設定が適用された(例えば、収束が起こった)場合、 bmOperationFlags:D0 ビットを0に設定する必要があり、SET_CUR(NORMAL)要求の後に来たSET_CUR(CANCEL)要求のために設定が適用されなかった(例えば、まだ収束が起こっていない)場合、1に設定する必要があります。
2.2.2.2 フォーカスコントロール
このコントロールにより、ホスト ソフトウェアはカメラのフォーカス設定を指定できます。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。
このコントロールは、キャンセル可能なコントロールとして機能する必要があります (GET_INFO 要求の要件と SET_CUR 要求の機能動作については、セクション 2.2.2.1 を参照)。
GET_MAX 要件: このコントロールは、 bmControlFlags でビット D0、D1、D2、D8、および D18 のサポートをアドバタイズします。
GET_DEF要件: bmControlFlags の既定値は、D0 と D18 を 1 に、 dwValue を 0 に設定する必要があります。
GET_CUR/Standard Edition T_CUR要求の場合、フィールド bmControlFlags には次の制限が適用されます。
D0、D1、D8 ビットのうち、設定できるビットは 1 つだけです。D2 ビットが設定されている場合、それらのいずれも有効ではありません。
D16、D17、D18、D19、D20 のうち、1 ビットのみ設定可能であり、どれを設定しても無効です。
D1 は、現在定義されている他のすべてのビット (D0、D2、D8、D16、D17、D18、D19、および D20) と互換性がありません。
D2 は D1 および D8 と互換性がありません。
D0 が設定されていない場合、D2 は D16、D17、D18、D19、および D20 と互換性がありません。
2.2.2.3 露出コントロール
このコントロールにより、ホスト ソフトウェアはカメラの露出設定を指定できます。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。
GET_INFO要求は、このコントロールを非同期コントロール (たとえば、D4 ビットを 1 に設定する) と報告しますが、AutoUpdate コントロールとしては報告しません (たとえば、D3 ビットを 0 に設定する)。
GET_MAX 要件: このコントロールは、 bmControlFlags でビット D0、D1、および D2 のサポートをアドバタイズします。
GET_DEF要件: bmControlFlags の既定値は、D0 を 1 に、 dwValue を 0 に設定する必要があります。
GET_CUR/Standard Edition T_CUR要求の場合、フィールド bmControlFlags には次の制限が適用されます。
- D0、D1、D2 ビットのうち、少なくとも 1 ビットを設定する必要があります。
- D1 は D0 および D2 と互換性がありません。
2.2.2.4 EV 補正コントロール
このコントロールにより、ホスト ソフトウェアはカメラの EV 補正設定を指定できます。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。
GET_INFO要求は、このコントロールを非同期コントロール (たとえば、D4 ビットを 1 に設定する) と報告しますが、AutoUpdate コントロールとしては報告しません (たとえば、D3 ビットを 0 に設定する)。
GET_RES要求では、 bmControlFlags で対応するビットを設定することによって、サポートされているすべての解像度 (ステップ サイズ) を報告します。 その他のフィールドはすべて 0 に設定します。
GET_MIN要求とGET_MAX要求は、 dwValueでサポートされる最小値と最大値を報告します。 ビット D4 (ステップ サイズ 1 を示す) は、 bmControlFlagsで設定された 1 つだけのビットでなければなりません。 その他のフィールドはすべて 0 に設定します。
GET_DEF、GET_CUR、SET_CUR リクエストはセクション 2.2.2.1 の定義に従いますが、フィールド bmControlFlags の D0、D1、D2、D3、および D4 ビットのうち 1 つだけのビット セットを持たなければなりません。 さらに、GET_DEF要求では dwValue が 0 に設定されている必要があります。
2.2.2.5 ホワイトバランスコントロール
このコントロールにより、ホスト ソフトウェアはカメラのホワイト バランス設定を指定できます。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。
GET_INFO要求は、このコントロールを非同期コントロール (たとえば、D4 ビットを 1 に設定する) と報告しますが、AutoUpdate コントロールとしては報告しません (たとえば、D3 ビットを 0 に設定する)。
GET_RES、GET_MIN、GET_MAX要求はセクション 2.2.2.1 の定義に従うものの、 dwValueFormat を 1 に設定する必要があります。
GET_MAX 要件: このコントロールは、 bmControlFlags でビット D0、D1、および D2 のサポートをアドバタイズします。
GET_DEF 要件: bmControlFlags のデフォルトは、D0 が 1 に設定され、 dwValueFormat と dwValue が 0 に設定されます。
GET_CUR/Standard Edition T_CUR要求の場合、フィールド bmControlFlags には次の制限が適用されます。
- D0、D1、D2 ビットのうち、少なくとも 1 ビットを設定する必要があります。
- D1 は D0 および D2 と互換性がありません。
2.2.2.6 顔認証コントロール
このコントロールを使用すると、ホスト ソフトウェアは、カメラが顔認証に使用されるストリーミング モードをサポートするかどうかを指定できます。 このコントロールのサポートは、カメラが顔認証が可能であることを意味します。 それ以外の場合、このコントロールはサポートされません。
このコントロールは、Infra-Red (IR) データを生成できるカメラにのみ適用され、指定されたストリーミング インターフェイス (ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイスのサブセット) にのみ適用されます。
GET_RES要求とGET_MIN要求は、フィールド bNumEntries を 0 に設定して報告するため、追加のフィールドはありません。
GET_MAX要求の場合、 bmControlFlags フィールドで 1 にビットが設定されている場合、対応するモードがそのストリーミング インターフェイスでサポートされていることを示します。 GET_MAX リクエストの出力には、D1 または D2 のいずれかが可能なストリーミング インターフェイスのみがリストされます (たとえば、ストリーミング インターフェイスが D1 または D2 のいずれかが可能であればリストされます。それ以外の場合はリストされません)。 また、D1 と D2 の両方が可能とアドバタイズされるストリーミング インターフェイスはありません。 ストリーミング インターフェイスも汎用の方法 (顔認証の目的外など) で使用する場合は、そのストリーミング インターフェイスに対して (D1/D2 に加えて) D0 を 1 に設定する必要があります。
GET_DEF/GET_CUR/SET_CUR要求の場合、bmControlFlags フィールドで 1 に設定されたビットは、そのストリーミング インターフェイスに対応するモードが選択されていることを示します。 これらの要求では、特定のストリーミング インターフェイスに対して 1 つのみ 1 ビット (D0、D1 & D2 の中で) を設定する必要があります。 既定の選択肢 (実装固有) を返すGET_DEF要求の場合、ストリーミング インターフェイスも汎用の方法 (顔認証の目的外など) で使用する場合は、そのストリーミング インターフェイスで D0 を既定で 1 に設定する必要があります。それ以外の場合は、D1 または D2 (両方ではなく) が既定で 1 に設定されます。 GET_DEF/GET_CUR要求出力には、GET_MAX要求出力にリストされているすべてのストリーミング インターフェイスに関する情報が含まれますが、SET_CUR要求には、要求出力に GET_MAXリストされているストリーミング インターフェイスのサブセットのみが含まれる場合があります。
例:
カメラにそれぞれ番号 0x03、0x05、0x08、および 0x0b を持つ 4 つのビデオ ストリーミング インターフェイスがあり、ビデオ ストリーミング インターフェイス 0x05 が RGB データを生成し、残りの 3 つのビデオ ストリーミング インターフェイスが IR データを生成すると仮定します。 IR データを生成するストリーミング インターフェイスの中で、ストリーミング インターフェイス 0x03と 0x0b の両方が D1 に対応しているが、ストリーミング インターフェイス 0x03は D0 にも対応しているとします。 この例では、顔認証制御は 0x03 および 0x0b の番号が付いたストリーミング インターフェイスにのみ適用されるため、これらのインターフェイスのみが要求に表示されます。
GET_MAX要求の出力は次のようになります。
GET_DEF要求の出力は次のようになります。
ストリーミング インターフェイス0x03の設定を D1 に変更するSET_CUR要求は次のようになります。
上記のSET_CUR要求の後のGET_CUR要求の出力は、次のようになります。
2.2.2.7 カメラ 外部コントロール
このコントロールにより、ホスト ソフトウェアは、ビデオ コントロール インターフェイスに関連付けられているビデオ ストリーミング インターフェイス上のエンドポイントのカメラ 外部データを取得できます。 このようにして各エンドポイントに対して取得されたデータは、対応するストリームの属性ストアに属性 MFStreamExtension_CameraExtrinsics として表示されます (IMFDeviceTransform::GetOutputStreamAttributes 呼び出しを使用して取得)。
GET_RES、GET_MIN、GET_MAX、GET_CUR要求は、フィールド bNumEntries を 0 に設定して報告するため、追加のフィールドはありません。
GET_DEF要求には、使用可能な外部情報を持つすべてのエンドポイントが一覧表示されます。
例:
カメラに、それぞれ番号 0x03、0x05、および 0x08 を持つ 3 つのビデオ ストリーミング インターフェイスがあり、ビデオ ストリーミング インターフェイス 0x05 は、すべてのビデオ ストリーミング インターフェイスでサポートされるビデオ キャプチャに加えて、メソッド 2 を使用した静止画キャプチャをサポートすると仮定します。 これらのストリーミング インターフェイスの中で、ストリーミング インターフェイス0x05と0x08では外部情報が使用可能であるが、ストリーミング インターフェイス0x03には 外部情報が使用できないとします。
この例では、GET_DEF要求の出力は次のようになります。
2.2.2.8 カメラ 組み込みコントロール
このコントロールにより、ホスト ソフトウェアは、ビデオ コントロール インターフェイスに関連付けられているビデオ ストリーミング インターフェイス上のエンドポイントのカメラ 組み込みデータを取得できます。 このようにして各エンドポイントに対して取得されたデータは、対応するストリームの属性ストアの属性 MFStreamExtension_PinholeCameraIntrinsics として表示されます (IMFDeviceTransform::GetOutputStreamAttributes 呼び出しを使用して取得)。
GET_RES、GET_MIN、GET_MAX、GET_CUR要求は、フィールド bNumEntries を 0 に設定して報告するため、追加のフィールドはありません。
GET_DEF要求には、使用可能な組み込み情報を持つすべてのエンドポイントが一覧表示されます。
例:
カメラに、それぞれ番号 0x03、0x05、および 0x08 を持つ 3 つのビデオ ストリーミング インターフェイスがあり、ビデオ ストリーミング インターフェイス 0x05 は、すべてのビデオ ストリーミング インターフェイスでサポートされるビデオ キャプチャに加えて、メソッド 2 を使用した静止画キャプチャをサポートすると仮定します。 これらのストリーミング インターフェイスのうち、ストリーミング インターフェイス 0x05 と 0x08 には使用可能な組み込み情報があるが、ストリーミング インターフェイス 0x03 には使用可能な組み込み情報がないものとします。
この例では、GET_DEF要求の出力は次のようになります。
2.2.2.9 メタデータコントロール
このコントロールを使用すると、ホスト ソフトウェアはカメラによって生成されたメタデータのクエリと制御を行います。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。
このコントロールは、カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA にマップされます。
SET_CUR要求がファームウェアでサポートされている場合は、次のことが適用されます。
GET_MIN、GET_DEF要求では、 dwValue が 0 に設定されたフィールドを報告します。
GET_RES要求では、フィールド dwValue がGET_MAX要求によって報告された値と同じ値で報告されます。
SET_CUR要求で dwValue が 0 に設定されている場合、カメラはメタデータを生成しません。 dwValue がGET_MAXリクエストで報告された値と同じに設定されたSET_CURリクエストを受信した場合、カメラはメタデータを生成することができ、そのようなメタデータのサイズはどのフレームでも dwValue を超えることはできません。
SET_CUR リクエストがファームウェアでサポートされていない場合は、以下が適用されます。
GET_MIN、GET_DEF要求では、フィールド dwValue は、GET_MAX要求によって報告された値と同じ値で報告されます。
GET_RES要求では、 dwValue が 0 に設定されたフィールドを報告します。
カメラはメタデータを生成することができ、そのようなメタデータの合計サイズは、GET_MAXリクエストによって報告される dwValue から UsbVideoHeader メタデータのペイロードサイズを差し引いた1024バイトを超えることはできません。
UsbVideoHeader メタデータ ペイロードは、sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(KSTREAM_UVC_METADATA)、または 24 バイトです。
生成されるメタデータは、セクション 2.2.3 で説明されている Microsoft 標準形式のメタデータに準拠している必要があります。
2.2.2.10 IR トーチ コントロール
このコントロールは、IR LEDハードウェアがコントロールできる範囲を報告し、それをコントロールする能力を提供する柔軟な手段を提供します。 これは、カメラに接続されている IR ランプの電力を調整することによって、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。
このコントロールは、カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_IRTORCHMODE にマップされます。
次が該当します。
GET_LEN要求は、値 8 を報告します。
GET_INFO リクエストは値 3 を報告します。 この値は、GET_CURとSET_CURをサポートする同期コントロールを示します。
GET_MIN要求では、フィールド dwMode が 0 に設定され、 dwValue が最小電力を示す値に設定されます。 電源レベル 0 は OFF を示しますが、最小動作電力レベルは 0 である必要はありません。
GET_RES リクエストは、フィールド dwMode が 0 に設定され、 dwValue が GET_MAX(dwValue) – GET_MIN(dwValue) 以下の数値に設定され、GET_MAX(dwValue) – GET_MIN になることを報告します。 (dwValue) はその値で均等に割り切れます。 dwValue は 0 (0) にすることはできません。
GET_MAX要求では、このコントロールの機能を識別するために、フィールド dwMode セットをビット D[0-2] に設定して報告する必要があります。 dwMode には、OFF がサポートされていることを示すビット D0 が設定されている必要があり、アクティブな状態をサポートする、少なくとも 1 つの他のビットセットが必要です。 dwValue は、通常電力を示す値に設定する必要があります。
GET_DEF要求では、フィールド dwMode に、ストリーミング開始前にシステムが設定されるべき既定のモードを報告する必要があります。 dwMode は 2 (ON) または 4 (ALTERNATING) に設定します。 dwValue は、FaceAuth コントロールに通常使用される電力レベルに設定する必要があります。 dwValue は製造元によって定義されます。
GET_CUR 要求は、フィールド dwMode が現在の動作モードに設定され、 dwValue が現在の照明に設定されていることを報告する必要があります。
SET_CUR リクエストを受信すると、IR トーチはリクエストされた動作モードを使用して照明を比例強度に設定します。
IR トーチは、すべてのフレームに MF_CAPTURE_METADATA_FRAME_ILLUMINATION 属性を出力する必要があります。 これは、デバイス MFT を介して、またはカメラのメタデータ ペイロードにa MetadataId_FrameIllumination 属性を含めることで提供できます。 セクション 2.2.3.4.4 をご覧ください。
このメタデータの唯一の目的は、フレームが照らされているかどうかを示することです。 これは、 KSPROPERTY_CAMERACONTROL_EXTENDED_FACEAUTH_MODE DDIと、2.2.2.6セクションで定義されている MSXU_FACE_AUTHENTICATION_CONTROL で必要とされるメタデータと同じです。
2.2.2.11 デジタルウィンドウコントロール
デジタル ウィンドウでは、カメラのストリーミング中にカメラの視野とズームを指定します。 このコントロールは、パン、チルト、ズームの代替となる可能性があります。 このコントロールは、カメラがアクティブにストリーミングしている間にのみ適用されます。
このコントロールは、すべての種類のカメラで使用でき、ストリーミングされるメディアの種類に依存しません。
このコントロールを使用すると、ホスト ソフトウェアは、カメラに関連付けられているデジタル ウィンドウを照会および制御できます。
これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。 ISP が使用するピクセル データのソースを調整します。 これには、方法 2 と方法 3 静止画キャプチャピンが含まれます。
このコントロールは、受信トレイ カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW にマップされます。
次が該当します。
GET_LEN要求は、値 16 を報告します。
GET_INFO リクエストは値 3 を報告します。 この値は、GET_CURとSET_CURをサポートする同期コントロールを示します。
GET_MIN要求では、フィールド dwMode が 0 に設定され、 OriginX と OriginY が 0.0 に設定され 、WindowSize が 1.0 に設定されます。 この要求は現在使用されていません。
GET_RES 要求では、フィールド dwMode が 0 に設定され、 OriginX と OriginY が 0.0 に設定され WindowSize が 1.0 に設定されます。 この要求は現在使用されていません。
GET_MAX要求では、このコントロールの機能を識別するためにビット D0 が設定された dwMode フィールドを報告する必要があります。 値 0 は、手動モードのみがサポートされていることを示します。 値 1 は、自動顔フレーム モードがサポートされていることを示します。 これらのフィールドの残りの部分は使用されませんが、 OriginX と OriginY を 0.0 に、 WindowSize を 1.0 に設定することをお勧めします。
GET_DEF 要求では、フィールド dwMode が 0 に設定され、 OriginX と OriginY が 0.0 に設定され WindowSize が 1.0 に設定されます。 これは常に既定のウィンドウです。
GET_CUR要求は、現在の動作モードに設定されたフィールド dwMode を報告し、 OriginX、 OriginY および WindowSize は現在のデジタル ウィンドウを記述します。
SET_CUR リクエストを受信すると、カメラは選択された動作モードとデジタル ウィンドウに一致するように視野を調整します。
自動フェイスフレーミングモードが選択された場合、カメラはシーン内の主要な顔を完全に囲むウィンドウを選択し、 OriginX、 OriginY、および WindowSize は無視されます。 顔が見つからない場合は、デフォルトのウィンドウが使用されます。
デジタル ウィンドウに対する変更は、各サンプルのメタデータ ペイロードに反映される必要があります。
デジタル ウィンドウへの変更はすぐには反映されない場合がありますが、コントロールはすぐに応答する必要があります。 デジタル ウィンドウへの変更は、有効になるとすぐにフレームのメタデータ ペイロードで報告する必要があります。
2.2.2.12 デジタルウィンドウ構成コントロール
デジタル ウィンドウ 構成キャップ コントロールは、使用可能なすべての解像度を考慮して、カメラのスケーリング制限を指定します。 解像度はメディア タイプに依存しないため、同じディスプレイ解像度をアドバタイズする 2 つのメディアタイプが 1 つの機能に組み合わされます。
コントロール エンドポイントのサイズ制限により、このコントロールは最大 1820 の一意の解像度を記述できます。
このコントロールが存在する場合、デジタル ウィンドウ コントロールの機能を報告するには、常にこのコントロールを使用できる必要があります。
このコントロールは、受信トレイ カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW_CONFIGCAPS にマップされます。
次が該当します。
要求GET_LENペイロードのサイズ全体を報告する必要があります。 各解像度定義の長さは 36 バイトであるため、ペイロード サイズは 36 の倍数である必要があります。
GET_INFO要求は、1 を報告します。 この値は、GET_CURのみをサポートする同期コントロールを示します。
GET_CUR要求は、一連の機能を報告する必要があります。 機能構造のフィールドは、上記で定義されています。
GET_MIN、GET_MAX、GET_RES、GET_DEFの要求は使用されませんが、GET_CURと同じ値を返す必要があります。
SET_CUR リクエストはサポートされていません。
2.2.2.13 ビデオの HDR コントロール
このコントロールを使用すると、ホスト ソフトウェアはカメラがビデオ HDR をサポートするかどうかを指定できます。 このコントロールのサポートは、カメラがベスト エフォートとしてビデオ HDR を実行できることを意味します。 カメラが Video HDR をサポートしていない場合は、このコントロールを実装しないでください。
このコントロールは、カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_VIDEOHDR にマップされます。
次が該当します。
GET_LEN リクエストは、ペイロード全体のサイズ (たとえば、4 バイト) を報告します。
GET_INFO要求は、値 3 を報告します。 この値は、GET_CUR、SET_CURをサポートする同期コントロールを示します。
GET_CUR要求は、現在の動作モードに設定されたフィールド dwMode を報告する必要があります。
GET_DEF は、 dwMode が OFF (0) に設定されている必要があります。
GET_MAX要求では、使用可能な操作モード ([1 (オン/オフ)、3 (オン/オフ/自動)]) のサポートをアドバタイズする必要があります。 このコントロールでは、ON (1) のサポートが必須です。
GET_MINおよびGET_RES要求は 0 を報告しなければなりません。
SET_CUR要求では、モードを OFF (0)、ON (1)、または AUTO (2) のいずれかに設定する必要があります。
2.2.2.14 フレームレートスロットル制御
このコントロールにより、ホスト ソフトウェアはカメラがフレームレート スロットルをサポートするかどうかを指定できます。
このコントロールは、カメラがアクティブにストリーミングしている間にのみ適用されます。 アクティブにストリーミングするということは、プレビュー ピンまたはレコード ピンが KSSTATE_RUN の状態にあり、フレームを配信できる状態にあることを意味します。 セット上でストリームがアクティブでない場合、このコントロールは STATUS_INVALID_DEVICE_STATE を返す必要があります。
これがフィルター スコープ コントロールであっても、フレーム レート コントロールは、写真ピンや IR/深度などの非 RGB ストリームに影響を与えるべきではありません。 また、フレーム レート スロットルが有効な場合は、それに応じてサンプル期間も調整する必要があります。
このコントロールは、カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_FRAMERATE_THROTTLE にマップされます。
| コントロールセレクター | MSXU_CONTROL_FRAMERATE_THROTTLE |
|---|---|
| 必須のリクエスト | GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR, SET_CUR |
| オプションのリクエスト | |
| wLength | 20 |
| オフセット | フィールド | サイズ | 値 | 説明 |
|---|---|---|---|---|
| 0 | dwMode | 4 | フラグ | D0: 0 (OFF) または 1 (ON) D1 ～ D31: 予約されており、0 に設定されます。 |
| 4 | scaleFactorPercentage | 4 | 番号 | この値は Min と Max の範囲内である必要があり、Step 値の倍数に設定する必要があります。 たとえば、Min = 5、Max = 100、Step = 5 の場合、アプリケーションがフレーム レートを元の値の 80% に下げることを決定した場合、このメンバー値は 80 に設定する必要があります。 この値を適切に設定することで、アプリは新しいフレーム レートが元の値を超えたりゼロになったりすることがなく、元のフレーム レートを維持できるようにすることができます。 |
| 8 | min | 4 | 番号 | Min は少なくとも 1 つのステップ サイズに等しいか、ステップ サイズの倍数である必要があります (例: step1、Step2 など)。 最小値を 0 に設定することはできません。 |
| 12 | max | 4 | 番号 | Max は 100 に設定する必要があります。これは、フレーム レートを変更しないことを意味します。 |
| 16 | step | 4 | 番号 | ステップは Max の厳密な係数である必要があります (例: {Max % Step == 0})。 例: 1、2、4、5 など |
次が該当します。
GET_LEN リクエストは、ペイロード全体のサイズ (たとえば、20 バイト) を報告します。
GET_INFO要求は、値 3 を報告します。 この値は、GET_CUR、SET_CURをサポートする同期コントロールを示します。
GET_CUR リクエストは、フィールド dwMode が現在の動作モードに設定され、scaleFactorPercentage が現在のscaleFactor 値に設定されたことを報告します。 最小、最大、およびステップは、上の表で説明されている値を報告する必要があります。
GET_DEF では、dwMode が OFF(0)、scaleFactorPercentage=100、Min がデフォルトの最小値に設定され、max が 100 に設定され、step がデフォルトのステップ値に設定されます。 min と step の値は製造元によって定義される必要がありますが、上の表に記載されているガイドラインに従う必要があります。
GET_MAXリクエストは、利用可能な操作モードのサポートを告知し、値1 [ ON | OFF ] を報告します。 このコントロールでは、ON と OFF の両方のサポートが必須です。 Min、max、step、scaleFactorPercentage を既定値に設定できます。
GET_MINおよびGET_RES要求は 0 を報告しなければなりません。
SET_CUR リクエストでは、モードを OFF(0)、ON(1) のいずれかに設定する必要があります。 dwMode が ON に設定されている場合、scaleFactorPercentage が有効になります。 OFF の場合と ON の場合の両方で、scaleFactorPercentage は上の表で説明されているように有効である必要があります。
2.2.2.15 視野 2 Config コントロール
Field of View 2 Config コントロールは、サポートされる対角視野の度数の値を値の配列として指定します。 サポートされるすべての値は、理論上の最小値と最大値、1 度から 360 度の範囲内にある必要があります。
デバイスが連続的な視野値をサポートしたい場合は、サポートされているすべての値を報告する必要があります。 たとえば、デバイスがステップ サイズ 1 で 85 度から 60 度の対角視野をサポートしたい場合、このコントロールは値の配列 [85、84、83、82、…、62、61、60] を報告する必要があります。 。
Field of View 2 コントロールが存在する場合、機能をレポートするには、このコントロールを使用できる必要があります。
これは同期フィルターレベル制御です。
このコントロールは、カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_FIELDOFVIEW2_CONFIGCAPS にマップされます。
| コントロールセレクター | MSXU_CONTROL_FIELDOFVIEW2_CONFIG |
|---|---|
| 必須のリクエスト | GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR |
| オプションのリクエスト | |
| wLength | 4 バイト + Count × 4 バイト。 Count は一意の視野値の数です。 |
| オフセット | フィールド | サイズ | 値 | 説明 |
|---|---|---|---|---|
| 0 | dwDefaultFieldOfView | 4 | 番号 | デフォルトの対角視野は、FieldOfViewValues 配列で報告される値の 1 つである必要があります。 |
| 4 | FieldOfViewValues[0] | 4 | 番号 | 最初の視野値。これは最も広い FoV (視野) 値である必要があります。 |
| … | … | … | … | … |
| 4 + 4*(カウント-1) | ViewValues のフィールド [カウント -1] | 4 | 番号 | 最後の視野値。これは最も狭い FoV 値である必要があります。 |
次が該当します。
要求GET_LENペイロードのサイズ全体を報告する必要があります。
GET_INFO要求は、1 を報告します。 この値は、GET_CURのみをサポートする同期コントロールを示します。
GET_CUR リクエストは、デフォルトの FoV とサポートされている FoV 値の配列を降順で含むデータを報告します。 構造体のフィールドは上で定義されています。
GET_DEF リクエストは GET_CUR と同じレポートを返します。
GET_MIN、GET_MAX、GET_RES リクエストは使用されませんが、GET_CUR と同じ値を返す必要があります。
SET_CUR リクエストはサポートされていません。
視野の値は降順である必要があります。たとえば、最も広い視野が最初で、最も狭い視野が最後になります。
2.2.2.16 視野 2 の制御
このコントロールは、ストリーミング時にカメラが使用する基本視野を指定します。 このコントロールはストリーミング前またはストリーミング中に適用できます。
このコントロールは、すべての種類のカメラで使用でき、ストリーミングされるメディアの種類に依存しません。
この制御により、ホスト ソフトウェアはカメラに関連付けられた視野をクエリおよび制御できるようになります。
これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。 ISP (画像信号プロセッサ) が使用するピクセル (またはセンサー) データのソースを調整します。 これには、方法 2 と方法 3 静止画キャプチャピンが含まれます。
これは同期フィルターレベル制御です。
このコントロールは、カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_FIELDOFVIEW2 にマップされます。
| コントロールセレクター | MSXU_CONTROL_FIELDOFVIEW2 |
|---|---|
| 必須のリクエスト | GET_INFO, GET_LEN, GET_RES, GET_MIN, GET_MAX, GET_DEF, GET_CUR, SET_CUR |
| オプションのリクエスト | |
| wLength | 4 |
| オフセット | フィールド | サイズ | 値 | 説明 |
|---|---|---|---|---|
| 0 | dwValue | 4 | 番号 | 対角視野の値 (度単位)。 |
次が該当します。
GET_LEN リクエストは値 4 を報告します。
GET_INFO要求は、3 を報告します。 この値は、GET_CURとSET_CURをサポートする同期コントロールを示します。
GET_MIN リクエストは、サポートされる最小視野値に設定されたフィールド dwValue を報告します。
GET_RES リクエストは、フィールド dwValue セット 0 を報告する必要があります。 この要求は現在使用されていません。
GET_MAX リクエストは、サポートされる最大視野値に設定されたフィールド dwValue を報告します。
GET_DEF リクエストは、デフォルトの Field of View 値に設定されたフィールド dwValue を報告します。
GET_CUR リクエストは、現在の Field of View 値に設定されたフィールド dwValue を報告します。
SET_CUR リクエストを受信すると、カメラは指定された dwValue に一致するように視野を設定します。
カメラが CT_ZOOM_RELATIVE_CONTROL および/または CT_ZOOM_ABSOLUTE_CONTROL を実装している場合、MSXU_CONTROL_FIELDOFVIEW2 SET_CUR が呼び出されたときに、これらのコントロールはデフォルト値にリセットされます。
カメラが MSXU_CONTROL_DIGITALWINDOW を実装している場合、新しい視野値が設定されたときにウィンドウの変更が反映されます。 逆も同様で、視野にはデジタル ウィンドウ経由で行われた変更が反映されます。 詳細については、「KSPROPERTY_CAMERACONTROL_EXTENDED_FIELDOFVIEW2」を参照してください。
2.2.3 メタデータ
標準形式のフレーム メタデータの設計は、Windows 10 の UVC カスタム メタデータ 設計に基づいています。 Windows 10では、カメラドライバ用のカスタム INF を使用することで、UVC 用のカスタムメタデータがサポートされます (注：カメラドライバは Windows の USBVIDEO.SYS をベースにすることができますが、メタデータを取得するには、指定されたハードウェア用のカスタム INF が必要です)。 MetadataBufferSizeInKB<PinIndex> 個のレジストリ エントリが存在し、ゼロ以外の場合、そのピンに対してカスタム メタデータがサポートされ、その値はメタデータに使用されるバッファ サイズを示します。 この <PinIndex> フィールドは、ビデオ ピン インデックスの 0 ベースのインデックスを示します。
Windows 10 バージョン 1703 では、カメラ ドライバーは、次の AddReg エントリを含めることで、Microsoft 標準形式のメタデータのサポートを通知できます。
StandardFormatMetadata<PinIndex>: REG_DWORD: 0x0 (未サポート) から 0x1 (サポート)
このレジストリ キーは DevProxy によって読み取られ、 KSSTREAM_METADATA_INFO 構造のフラグ フィールドにフラグ KSSTREAM_METADATA_INFO_FLAG_STANDARDFORMATを設定することによって、メタデータが標準形式であることを UVC ドライバーに通知します。
2.2.3.1 Microsoft 標準フォーマットのメタデータ
Microsoft 標準フォーマットのメタデータは、次の構造の 1 つ以上のインスタンスです。
typedef struct tagKSCAMERA_METADATA_ITEMHEADER {
ULONG MetadataId;
ULONG Size; // Size of this header + metadata payload following
} KSCAMERA_METADATA_ITEMHEADER, *PKSCAMERA_METADATA_ITEMHEADER;
MetadataId フィールドには、明確に定義された識別子とカスタム識別子 (識別子 >= MetadataId_Custom_Start) を含む次の列挙型定義の識別子が入力されます。
typedef enum {
MetadataId_Standard_Start = 1,
MetadataId_PhotoConfirmation = MetadataId_Standard_Start,
MetadataId_UsbVideoHeader,
MetadataId_CaptureStats,
MetadataId_CameraExtrinsics,
MetadataId_CameraIntrinsics,
MetadataId_FrameIllumination,
MetadataId_Standard_End = MetadataId_FrameIllumination,
MetadataId_Custom_Start = 0x80000000,
} KSCAMERA_MetadataId;
[サイズ] フィールドは sizeof(KSCAMERA_METADATA_ITEMHEADER) + sizeof(Metadata Payload) に設定されます。
2.2.3.2 USB ビデオ フレーム パケットからファームウェアによって生成された標準形式のメタデータ
フレーム ベースのビデオの UVC 経由の転送中に、ビデオ フレームは一連のパケットにパケット化され、その前に UVC ペイロード ヘッダーが付きます。 各 UVC ペイロード ヘッダーは、USB ビデオ クラス ドライバー フレーム ベースのペイロード仕様によって定義されます。
ペイロード ヘッダー
フレーム ベースの形式のペイロード ヘッダー形式の説明を次に示します。
HLE (ヘッダーの長さ) フィールド
ヘッダー長フィールドは、ヘッダーの長さをバイト単位で指定します。
ビット フィールド ヘッダー フィールド
ID: フレーム識別子
- このビットは、各フレームの開始境界で切り替え、フレームの残りの部分では一定のままです。
EOF: フレームの終わり
- このビットはビデオ フレームの末尾を示し、フレームに属する最後のビデオ サンプルで設定されます。 このビットの使用は、フレーム転送の完了時の待機時間を短縮するための最適化であり、省略可能です。
PTS: プレゼンテーション タイム スタンプ。
- このビットを設定されている場合、PTS フィールドが存在します。
SCR: ソース クロック リファレンス
- このビットを設定されている場合、SCR フィールドが存在します。
RES: 予約済み。
- を 0 に設定します。
STI: 静止画
- このビットを設定すると、ビデオ サンプルが静止画像に属するものとして識別されます。
ERR: エラー ビット
- このビットを設定すると、デバイス ストリーミングでエラーが示されます。
EOH: ヘッダーの終わり
- このビットを設定すると、BFH フィールドの末尾が示されます。
PTS: プレゼンテーション タイムスタンプ、サイズ: 4 バイト、値: 数値
- PTS フィールドは、BFH[0] フィールドに PTS ビットが設定されている場合に存在します。 ビデオ デバイスの USB デバイス クラス定義 仕様のセクション 2.4.3.3 「ビデオおよび静止画像ペイロード ヘッダー」を参照してください。
SCR: ソース クロック リファレンス、サイズ: 6 バイト、値: 数値
- SCR フィールドは、BFH[0] フィールドに SCR ビットが設定されている場合に存在します。 ビデオ デバイスの USB デバイス クラス定義 仕様のセクション 2.4.3.3 「ビデオおよび静止画像ペイロード ヘッダー」を参照してください。
既存の UVC ドライバーの HLE フィールドは、2 バイト (PTS/SCR が存在しない) または最大 12 バイト (PTS/SCR が存在する) に固定されています。 ただし、バイト サイズのフィールドである HLE フィールドでは、最大 255 バイトのヘッダー データを指定できます。 両方の PTS/SCR が存在し、HLE が 12 バイトより大きい場合、INF エントリ StandardFormatMetadata<PinIndex> が設定されたときに、ペイロード ヘッダーの最初の 12 バイトに続く追加データは、ビデオ フレームに固有の標準メタデータとして取得されます。
フレームの (ファームウェアによって生成される) 標準形式のメタデータは、そのフレームを表すビデオ フレーム パケットで見つかった部分 BLOB を連結することによって取得されます。
2.2.3.3 ユーザー モード コンポーネントに提供されるメタデータ バッファー
ユーザー モード コンポーネントに提供されるメタデータ バッファーには、UVC タイムスタンプ (UVC ドライバーによって生成される) のメタデータ項目があり、その後にファームウェアによって生成されるメタデータ項目が続き、次のようにレイアウトされます。
2.2.3.4 標準メタデータ識別子のメタデータ形式
ファームウェアは、識別子に対応するメタデータを生成するかどうかを選択できます。 ファームウェアが識別子に対応するメタデータを生成することを選択した場合、その識別子のメタデータは、ファームウェアによって出力されるすべてのフレームに存在する必要があります。
2.2.3.4.1 MetadataId_CaptureStats
この識別子のメタデータ形式は、次の構造によって定義されます。
typedef struct tagKSCAMERA_METADATA_CAPTURESTATS {
KSCAMERA_METADATA_ITEMHEADER Header;
ULONG Flags;
ULONG Reserved;
ULONGLONG ExposureTime;
ULONGLONG ExposureCompensationFlags;
LONG ExposureCompensationValue;
ULONG IsoSpeed;
ULONG FocusState;
ULONG LensPosition; // a.k.a Focus
ULONG WhiteBalance;
ULONG Flash;
ULONG FlashPower;
ULONG ZoomFactor;
ULONGLONG SceneMode;
ULONGLONG SensorFramerate;
} KSCAMERA_METADATA_CAPTURESTATS, *PKSCAMERA_METADATA_CAPTURESTATS;
Flags フィールドは、構造体内の後のフィールドのうち、どのフィールドに入力され、有効なデータが含まれているかを示します。 Flags フィールドはフレームごとに変わるものではありません。 現在、次のフラグが定義されています。
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_EXPOSURETIME 0x00000001
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_EXPOSURECOMPENSATION 0x00000002
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_ISOSPEED 0x00000004
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FOCUSSTATE 0x00000008
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_LENSPOSITION 0x00000010
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_WHITEBALANCE 0x00000020
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FLASH 0x00000040
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FLASHPOWER 0x00000080
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_ZOOMFACTOR 0x00000100
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_SCENEMODE 0x00000200
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_SENSORFRAMERATE 0x00000400
予約済み フィールドは将来のために予約され、0 に設定されます。
ExposureTime フィールドには、フレームがキャプチャされたときにセンサーに適用された露出時間が 100 ns 単位で含まれます。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_EXPOSURE_TIME として表示されます。
ExposureCompensationFlags フィールドには、EV 補正値を伝達するために使用される EV 補正ステップ (KSCAMERA_EXTENDEDPROP_EVCOMP_XXX ステップ フラグの 1 つを設定する必要があります) が含まれています。 ExposureCompensationValue フィールドには、フレームのキャプチャ時にセンサーに適用されたステップの単位で EV 補正値が含まれます。 これらは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION として表示されます。
IsoSpeed フィールドには、フレームのキャプチャ時にセンサーに適用される ISO 速度値が含まれます。 これには単位がありません。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_ISO_SPEED として表示されます。
FocusState フィールドには、列挙型 KSCAMERA_EXTENDEDPROP_FOCUSSTATE で定義された値の 1 つを取ることができる現在のフォーカス状態が含まれます。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_FOCUSSTATE として表示されます。
LensPosition フィールドには、フレームがキャプチャされたときの論理レンズ位置 (単位なし) が含まれます。 これは、GET 呼び出しの KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS からクエリできる値と同じです。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_LENS_POSITION として表示されます。
WhiteBalance フィールドには、フレームのキャプチャ時にセンサーに適用されるホワイト バランス (Kelvin の値) が含まれます。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_WHITEBALANCE として表示されます。
Flash フィールドにはブール値が含まれ、フレームのキャプチャ時にフラッシュが 1、フラッシュオフが 0 になります。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_FLASH として表示されます。
FlashPower フィールドには、キャプチャされたフレームに適用されるフラッシュ電力が含まれています。これは、[0, 100] の範囲の値です。 ドライバーがフラッシュの調整可能な電力をサポートしていない場合、このフィールドは省略する必要があります。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_FLASH_POWER として表示されます。
ZoomFactor フィールドには、キャプチャしたフレームに適用される Q16 形式のズーム値が含まれます。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_ZOOMFACTOR として表示されます。
SceneMode フィールドには、キャプチャされたフレームに適用されるシーン モード (64 ビット KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX フラグ) が含まれます。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_SCENE_MODE として表示されます。
SensorFramerate フィールドには、フレームがキャプチャされたときに測定されたセンサーの読み出しレートが含まれます (Hz 単位)。分子の値が上位 32 ビットで、分母の値が下位 32 ビットで構成されます。 これは、対応する MF サンプルの属性 MF_CAPTURE_METADATA_SENSORFRAMERATE として表示されます。
2.2.3.4.2 MetadataId_CameraExtrinsics
この識別子のメタデータ形式には、標準のKSCAMERA_METADATA_ITEMHEADERの後にバイト配列ペイロードが含まれます。 ペイロードは、 MFCameraExtrinsics 構造体の後に 0 個以上の MFCameraExtrinsic_CalibratedTransform 構造体が続く必要があります。 ペイロードは 8 バイトでアラインされている必要があり、未使用のすべてのバイトはペイロードの最後に発生し、0 に設定されます。
2.2.3.4.3 MetadataId_CameraIntrinsics
この識別子のメタデータ形式には、標準のKSCAMERA_METADATA_ITEMHEADERの後にバイト配列ペイロードが含まれます。 ペイロードは、 MFPinholeCameraIntrinsics 構造体に配置する必要があります。 ペイロードは 8 バイトでアラインされている必要があり、未使用のすべてのバイトはペイロードの最後に発生し、0 に設定されます。
2.2.3.4.4 MetadataId_FrameIllumination
この識別子のメタデータ形式は、次の構造によって定義されます。
typedef struct tagKSCAMERA_METADATA_FRAMEILLUMINATION {
KSCAMERA_METADATA_ITEMHEADER Header;
ULONG Flags;
ULONG Reserved;
} KSCAMERA_METADATA_FRAMEILLUMINATION, *PKSCAMERA_METADATA_FRAMEILLUMINATION;
Flags フィールドは、キャプチャされたフレームに関する情報を示します。 現在、次のフラグが定義されています。
#define KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON 0x00000001
照明がオンのときにフレームがキャプチャされた場合は、フラグ KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ONを設定する必要があります。 それ以外の場合、このフラグは設定されません。
Reserved フィールドは将来のために予約され、0 に設定されます。
例:
例として、照明がオンであることを示すKSCAMERA_METADATA_FRAMEILLUMINATION構造は次のようになります。
KSCAMERA_METADATA_FRAMEILLUMINATION.Header.MetadataId = MetadataId_FrameIllumination;
KSCAMERA_METADATA_FRAMEILLUMINATION.Header.Size = 16; // 4 ULONG variables in total inside the structure
KSCAMERA_METADATA_FRAMEILLUMINATION.Flags = KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON;
KSCAMERA_METADATA_FRAMEILLUMINATION.Reserved = 0;
2.2.3.4.5 MetadataId_USBVideoHeader
この識別子のメタデータ形式は、共通のKSCAMERA_METADATA_ITEMHEADERの後にKSSTREAM_UVC_METADATA構造体によって定義されます。
typedef struct
{
ULONG PresentationTimeStamp;
ULONG SourceClockReference;
union
{
struct
{
USHORT Counter : 11;
USHORT Reserved : 5;
};
USHORT SCRToken;
};
USHORT Reserved0;
ULONG Reserved1;
} KSSTREAM_UVC_METADATATYPE_TIMESTAMP, *PKSSTREAM_UVC_METADATATYPE_TIMESTAMP;
typedef struct {
KSSTREAM_UVC_METADATATYPE_TIMESTAMP StartOfFrameTimestamp;
KSSTREAM_UVC_METADATATYPE_TIMESTAMP EndOfFrameTimestamp;
} KSSTREAM_UVC_METADATA, *PKSSTREAM_UVC_METADATA;
StartOfFrameTimestamp と EndOfFrameTimestamp フィールドは、このフレームを構築するためにカメラによって発行された最初と最後の UVC ペイロードの UVC ヘッダーに含まれるタイムスタンプです。
このペイロードはデバイスによって送信されるべきではありません。
このメタデータ ペイロードは、UVC 準拠のペイロード ヘッダーから取得した情報から USB Video クラス ドライバーによって直接生成される唯一のメタデータ ペイロードであるという点で独特です。
このペイロードは、各フレームのメタデータ バッファーの前に追加されます。
デバイスが標準化されたメタデータをサポートしている場合は、セクション 2.2.2.9 で定義されているメタデータ コントロールによって報告されるバッファー要件に、このペイロードを格納するために必要な領域を含める必要があります。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示