USB ビデオ クラス 1.5 仕様に対する Microsoft の拡張機能

  • [アーティクル]

1 概要

1.1 まとめ

USB ビデオ クラス仕様に対する Microsoft の拡張機能により、新しいコントロールと、適切に定義されたフレーム メタデータを標準形式で伝送する機能が有効になります。

1.2 アーキテクチャの決定

USB ビデオ クラス (UVC) フレーム メタデータのサポートは、ISOCH および一括エンドポイントで使用できます。 ただし、BULK エンドポイントの場合、メタデータ サイズは 240 バイトに制限されます (すべてのビデオ フレーム データが BULK エンドポイント上の 1 つのビデオ フレーム パケットで転送されるため)。

UVC メタデータのサポートは、フレーム ベースのペイロードでのみ使用できます。

UVC メタデータのサポートは、メディア ファンデーション (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 を利用していませんでした。

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 フィールドのビット位置にマップしたものです。

extension unit controls.

2.2.2.1 キャンセル可能なコントロール

ここでは、Autoupdate 機能を利用してキャンセル可能なコントロールを定義します。

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 フォーカスコントロール

このコントロールにより、ホスト ソフトウェアはカメラのフォーカス設定を指定できます。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。

focus control.

このコントロールは、キャンセル可能なコントロールとして機能する必要があります (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 露出コントロール

このコントロールにより、ホスト ソフトウェアはカメラの露出設定を指定できます。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。

exposure control.

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 補正設定を指定できます。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。

E V compensation control.

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 つだけ、1 ビットしか設定できません。 さらに、GET_DEF要求では dwValue が 0 に設定されている必要があります。

2.2.2.5 ホワイトバランスコントロール

このコントロールにより、ホスト ソフトウェアはカメラのホワイト バランス設定を指定できます。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。

white balance control.

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) データを生成できるカメラにのみ適用され、指定されたストリーミング インターフェイス (ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイスのサブセット) にのみ適用されます。

face authentication control.

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要求の出力は次のようになります。

face authentication GET_MAX.

GET_DEF要求の出力は次のようになります。

face authentication GET_DEF.

ストリーミング インターフェイス0x03の設定を D1 に変更するSET_CUR要求は次のようになります。

face authentication SET_CUR.

上記のSET_CUR要求の後のGET_CUR要求の出力は、次のようになります。

face authentication GET_CUR.

2.2.2.7 カメラ 外部コントロール

このコントロールにより、ホスト ソフトウェアは、ビデオ コントロール インターフェイスに関連付けられているビデオ ストリーミング インターフェイス上のエンドポイントのカメラ 外部データを取得できます。 したがって、各エンドポイントで取得されたデータは、対応するストリームの属性ストアの属性 MFStreamExtension_CameraExtrinsics として表示されます (IMFDeviceTransform::GetOutputStreamAttributes 呼び出しを使用して取得されます)。

camera extrinsics control.

GET_RES、GET_MIN、GET_MAX、GET_CUR要求は、フィールド bNumEntries を 0 に設定して報告するため、追加のフィールドはありません。

GET_DEF要求には、使用可能な外部情報を持つすべてのエンドポイントが一覧表示されます。

例:

カメラには、0x03、0x05、0x08の 3 つのビデオ ストリーミング インターフェイスがあり、ビデオ ストリーミング インターフェイス0x05では、すべてのビデオ ストリーミング インターフェイスでサポートされているビデオ キャプチャに加えて、方法 2 を使用した静止画像キャプチャがサポートされていると仮定します。 これらのストリーミング インターフェイスの中で、ストリーミング インターフェイス0x05と0x08では外部情報が使用可能であるが、ストリーミング インターフェイス0x03には 外部情報が使用できないとします。

この例では、GET_DEF要求の出力は次のようになります。

camera extrinsics GET_DEF.

2.2.2.8 カメラ 組み込みコントロール

このコントロールにより、ホスト ソフトウェアは、ビデオ コントロール インターフェイスに関連付けられているビデオ ストリーミング インターフェイス上のエンドポイントのカメラ 組み込みデータを取得できます。 したがって、各エンドポイントで取得されたデータは、対応するストリームの属性ストアの属性 MFStreamExtension_PinholeCameraIntrinsics として表示されます (IMFDeviceTransform::GetOutputStreamAttributes 呼び出しを使用して取得されます)。

camera intrinsics control.

GET_RES、GET_MIN、GET_MAX、GET_CUR要求は、フィールド bNumEntries を 0 に設定して報告するため、追加のフィールドはありません。

GET_DEF要求には、使用可能な組み込み情報を持つすべてのエンドポイントが一覧表示されます。

例:

カメラには、0x03、0x05、0x08の 3 つのビデオ ストリーミング インターフェイスがあり、ビデオ ストリーミング インターフェイス0x05では、すべてのビデオ ストリーミング インターフェイスでサポートされているビデオ キャプチャに加えて、方法 2 を使用した静止画像キャプチャがサポートされていると仮定します。 これらのストリーミング インターフェイスの中で、ストリーミング インターフェイス0x05と0x08では組み込み情報が使用可能であるが、ストリーミング インターフェイス0x03には組み込み情報が使用できないとします。

この例では、GET_DEF要求の出力は次のようになります。

camera intrinsics GET_DEF.

2.2.2.9 メタデータコントロール

このコントロールを使用すると、ホスト ソフトウェアはカメラによって生成されたメタデータのクエリと制御を行います。 これは、ビデオ コントロール インターフェイスに関連付けられているすべてのビデオ ストリーミング インターフェイス上のすべてのエンドポイントに影響を与えるグローバル コントロールです。

このコントロールは、カメラ ドライバーによって KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA にマップされます。

metadata control.

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 に設定されたフィールドを報告します。
  • カメラはメタデータを生成でき、そのようなメタデータの合計サイズは dwValue (GET_MAX要求によって報告される) を超えることはできません。どのフレームでも、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 にマップされます。

I R torch control.

次が該当します。

  • 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 にマップされます。

digital window control.

次が該当します。

  • 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 にマップされます。

digital window config control.

次が該当します。

  • 要求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 にマップされます。

video H D R control.

次が該当します。

  • 要求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.3 メタデータ

標準形式のフレーム メタデータの設計は、Windows 10 の UVC カスタム メタデータ 設計に基づいています。 Windows 10では、カメラドライバ用のカスタム INF を使用することで、UVC 用のカスタムメタデータがサポートされます (注：カメラドライバは Windows の USBVIDEO.SYS をベースにすることができますが、メタデータを取得するには、指定されたハードウェア用のカスタム INF が必要です)。 MetadataBufferSizeInKB<PinIndex> レジストリ エントリが存在し、0 以外の場合は、そのピンに対してカスタム メタデータがサポートされ、値はメタデータに使用されるバッファー サイズを示します。 この<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 つ以上のインスタンスです。

standard format metadata.

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 ビデオ クラス ドライバー フレーム ベースのペイロード仕様によって定義されます。

ペイロード ヘッダー

フレーム ベースの形式のペイロード ヘッダー形式の説明を次に示します。

payload header.

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 を連結することによって取得されます。

metadata frame packets.

2.2.3.3 ユーザー モード コンポーネントに提供されるメタデータ バッファー

ユーザー モード コンポーネントに提供されるメタデータ バッファーには、(UVC ドライバーによって生成される) UVC タイムスタンプのメタデータ項目の後に、ファームウェアで生成されたメタデータ項目が続き、次のようにレイアウトされます。

metadata buffer.

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 フィールドには、フレームのキャプチャ時にセンサーに適用される露出時間が 100ns で含まれます。 これは、対応する 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 ビデオ クラス ドライバーによって直接生成される唯一のメタデータ ペイロードであるという点で一意です。

このペイロードは、各フレームのメタデータ バッファーの前に追加されます。

デバイスが標準化されたメタデータをサポートしている場合は、セクション 2.2.2.9 で定義されているメタデータ コントロールによって報告されるバッファー要件に、このペイロードを格納するために必要な領域を含める必要があります。