拡張カメラ コントロール
拡張コントロールでは、KSPROPERTY メカニズムを使用して、カメラ コントロールをアプリケーションに公開します。
以下の標準化された拡張コントロール (メディア ファンデーションによって定義) の一覧にあるものを使用すると、Windows カメラの追加機能が有効になります。
一部のコントロールは非同期コントロールとしてアプリケーションに公開され、その他のコントロールは同期コントロールとして公開されます。
同期コントロール
これらのコントロールに対し、キャプチャ パイプラインは KSPROPERTY カメラ コントロール構造体を発行し、ドライバーが同期的に要求を返すことを想定しています。
非同期コントロール
これらのコントロールに対し、キャプチャ パイプラインは KSPROPERTY を発行し、そのプロパティに関連付けられた KSEVENT を有効にし、イベントが通知されるまで待機します。 ドライバーは、KSPROPERTY を同期的に完了し、それを非同期操作を開始するトリガーとして使用する必要があります。 非同期操作が完了したら、ドライバーは、キャプチャ パイプラインが待機している関連する KSEVENT に通知する必要があります。 キャプチャ パイプラインは、シグナルを受信したときに、操作の完了についてアプリケーションに通知します。
非同期コントロールを取り消すことができる場合は、コントロールに KSCAMERA_EXTENDEDPROP_FLAG_CANCELOPERATION フラグを指定する必要があります。 コントロールを取り消すことができない場合、コントロールの操作は 5 ミリ秒を超えないようにする必要があります。
これらの拡張コントロールは、ksmedia.h で定義されている以下の KS プロパティ セットの一部です。
#define STATIC_KSPROPERTYSETID_ExtendedCameraControl \
0x1CB79112, 0xC0D2, 0x4213, 0x9C, 0xA6, 0xCD, 0x4F, 0xDB, 0x92, 0x79, 0x72
DEFINE_GUIDSTRUCT("1CB79112-C0D2-4213-9CA6-CD4FDB927972", KSPROPERTYSETID_ExtendedCameraControl);
#define KSPROPERTYSETID_ExtendedCameraControl DEFINE_GUIDNAMED(KSPROPERTYSETID_ExtendedCameraControl);
Metadata
メタデータを取得するには、ユーザー モード コンポーネント (DevProxy) がドライバーに対してメタデータ バッファー要件を照会する必要があります。 ユーザー モード コンポーネントは、この情報を取得すると、ドライバーに適切なメタデータ バッファーを割り当て、そこにメタデータを読み込みユーザー モード コンポーネントに返します。
KSPROPERTY_CAMERACONTROL_EXTENDED_PROPERTY列挙で定義されているKSPROPERTY_CAMERACONTROL_EXTENDED_METADATAプロパティ ID は、メタデータ バッファーの割り当てに必要なメタデータ サイズ、メモリ アラインメントの要件、必要なメモリ割り当ての種類など、メタデータ バッファーの要件を照会するためにクライアントが使用します。
ユーザー モード コンポーネントは、ドライバーからメタデータ バッファーの要件を取得すると、目的のメモリ プールから目的のメモリ アラインメントを使用して、適切なサイズのメタデータ バッファーを割り当てます。 このメタデータ バッファーは、実際のフレーム バッファーと共に、入力のためにドライバーへ送信され、その後、入力されるとユーザー モード コンポーネントに戻されます。 マルチショット シナリオでは、対応するメタデータ バッファーが割り当てられ、割り当てられた各フレーム バッファーのカメラ ドライバーに配信されます。
KSSTREAM_METADATA_INFO 構造体は、次のフラグと共に、ドライバーにメタデータ バッファーを送信するために使用されます。
#define KSSTREAM_HEADER_OPTIONSF_METADATA 0x00001000
バッファー (メタデータ + フレーム) がドライバーにキューされると、DevProxy は、標準の KSSTREAM_HEADER 構造体、KS_FRAME_INFO 構造体、そして KSSTREAM_METADATA_INFO 構造体の順に送信します。 DevProxy は、バッファーをドライバーに渡す前に、さらに KSSTREAM_HEADER.OptionFlags を KSSTREAM_HEADER_OPTIONSF_METADATA でマスクします。
ドライバーがメタデータをサポートしていないか、KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA が実装されていない場合は、KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA プロパティ コントロールが失敗します。 この場合、DevProxy はメタデータ バッファーを割り当てず、DevProxy からドライバーに渡されるペイロードには KSSTREAM_METADATA_INFO 構造体が含まれません。
ドライバーがメタデータをサポートしていて、クライアントがメタデータを必要としない場合、DevProxy はメタデータ バッファーを割り当てず、ドライバーにバッファーを送信するときに KSSTREAM_METADATA_INFO を受け渡しません。 この動作により、アプリが特定のピンにメタデータを必要としない場合に、不要なメタデータ メモリの割り当てが減ります。
次の構造体では、メタデータ バッファー内のカメラ ドライバーによって入力されるメタデータ項目のレイアウトについて説明します。
次の一覧には、メタデータ項目のレイアウトが含まれています。 これは、8 バイトでアラインされている必要があります。
Metadata
写真確認メタデータは、MetadataId_PhotoConfirmation によって識別されます。 存在する場合は、関連付けられているプレビュー フレームが写真確認フレームであることを示します。 写真確認メタデータは DevProxy によって解析されます。
カスタム メタデータは、MetadataId_Custom_Start から始まる MetadataId によって識別されます。 カスタム メタデータ項目には、フォーカス状態、プレビュー ピンのための顔検出、イメージ ピンのための EXIF、OEM の両方もしくは一方のメタデータといった、メタデータの塊が含まれていることがあります。 メタデータの塊であるカスタム BLOB の正確な形式は、ドライバーと MFT0 を実装する OEM によって決まります。 MFT0 は、カスタム BLOB を解析し、MF キャプチャ パイプラインや WinRT で読み取り可能な形式で、MFSampleExtension_CaptureMetadata 属性バッグの下にグループ化された属性として各メタデータ項目をアタッチする役割を担います。
次の IMFAttributes は mfapi.h で定義されています。 これらは、MF キャプチャ パイプラインまたは WinRT で必要です。 写真確認フレームは DevProxy を超えないため、MFT0 では写真確認に IMFAttributes が設定されないことに注意してください。
| 属性 (GUID) | データの種類 |
|---|---|
| MF_CAPTURE_METADATA_FOCUSSTATE | UINT32 |
| MF_CAPTURE_METADATA_FACEROIS | BLOB |
| MF_CAPTURE_METADATA_FRAME_RAWSTREAM | リンゴ、白 |
MF_CAPTURE_METADATA_FRAME_RAWSTREAM IMFAttributes は作成されると、DevProxy によって MFSampleExtension_CaptureMetadata にアタッチされます。これには、生のメタデータ バッファー (KSSTREAM_METADATA_INFO.Data) に関連付けられた IMFMediaBuffer インターフェイスのポインターが含まれています。
MFT0 が IMFSample を受け取ると、MF_CAPTURE_METADATA_FRAME_RAWSTREAM から生のメタデータ バッファーを取得し、フォーカス状態などの追加のカスタム メタデータ項目を解析して、上記に定義されている対応する IMFAttributes に変換し、MFSampleExtension_CaptureMetadata 属性バッグにアタッチします。 次の IMFAttribute は、MF パイプラインとサードパーティが提供する MFT によって引き継がれなければなりません。
| 名前 | Type |
|---|---|
| MFSampleExtension_CaptureMetadata | IUnknown (IMFAttributes) |
| MFSampleExtension_EOS | UINT32 (ブール型) |
| MFSampleExtension_PhotoThumbnail | IUnknown (IMFMediaBuffer) |
| MFSampleExtension_PhotoThumbnailMediaType | IUnknown (IMFMediaType) |
生のメタデータ バッファーにアクセスするために、MFT0 は次の処理を行います。
IMFSample インターフェイスから MFSampleExtension_CaptureMetadata で、GetUnknown を呼び出し、属性バッグの IMFAttributes インターフェイスを取得します。
前の手順で取得した IMFAttributes インターフェイスから MF_CAPTURE_METADATA_FRAME_RAWSTREAM で GetUnknown を呼び出して、IMFMediaBuffer インターフェイスを取得します。
Lock を呼び出して、IMFMediaBuffer に関連付けられている生のメタデータ バッファーを取得します。
必要な IMFAttributes を MFSampleExtension_CaptureMetadata 属性バッグに追加するために、MFT0 は次の処理を行います。
IMFSample インターフェイスから MFSampleExtension_CaptureMetadata で、GetUnknown を呼び出し、属性バッグの IMFAttributes インターフェイスを取得します。
上記の表で指定された GUID とデータ型に基づいて、前の手順で取得した IMFAttributes インターフェイスから MF_CAPTURE_METADATA_XXX で SetUINT32、SetBlob、または SetUnknown を呼び出します。
必須のメタデータ属性
使用可能なメタデータ属性の一覧については、統計メタデータ属性のキャプチャをご覧ください。
フォーカスの優先順位
KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUSPRIORITY プロパティ ID は、フォーカス優先度 DDI に関連付けられている唯一のコントロールです。
フォーカス状態
KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUSSTATE プロパティ ID は、フォーカス状態 DDI に関連付けられている唯一のコントロールです。
拡張関心領域 ROI
次のプロパティ ID は、ROI DDI に関連付けられているコントロールです。
写真確認
KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOCONFIRMATION プロパティ ID は、写真確認 DDI に関連付けられている唯一のコントロールです。
写真シーケンス サブモード
KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOMODE プロパティ ID は、写真シーケンス DDI に関連付けられている唯一のコントロールです。
EXIF および HW JPEG エンコーダー
パイプラインは、HW JPEG エンコーダーの EXIF データを処理または幾何補正する必要はありません。そのため、EXIF データ形式は、ドライバー、MFT0、および OEM HW JPEG エンコーダーによって提供されます。 OEM パートナーは、EXIF 属性のカスタム属性 GUID とバリアント型を定義し、OEM コンポーネントが使用するために MFSampleExtension_CaptureMetaData 属性バッグにアタッチできます。 HW JPEG エンコーダーが使用可能な場合、パイプライン写真シンク コンポーネントは HW JPEG エンコーダーを読み込み、MFSAMPLEEXTENSION_CAPTUREMETADATA 属性バッグに保持されている EXIF データを IPropertyBag2::Write メソッドを使用し、EXIF エンコーダー オプションとして HW JPEG エンコーダーに設定します。
エンコーダー オプション プロパティ バッグには、使用可能なエンコード オプションのプロパティを指定する PROPBAG2 構造体の配列が含まれています。 HW JPEG エンコーダーに設定された EXIF エンコーダー オプションは、エンコーダー オプション プロパティ バッグ内の次のプロパティによって識別されます。
| プロパティ名 | VARTYPE | Value | 適用可能なコーデック |
|---|---|---|---|
| SampleMetaData | VT_UNKNOWN | EXIF データを含んだ OEM サブ属性を含む MFSampleExtension_CaptureMetaData 属性バッグの IMFAttributes インターフェイスへのポインター。 | JPEG |
MFSampleExtension_CaptureMetaData 属性バッグには、MFT0 および HW JPEG エンコーダーが EXIF データを保持するために読み取ることができる OEM 定義の EXIF サブ属性のみを含めることができます。 ドライバーから HW JPEG エンコーダーに EXIF データを渡すには、ドライバーと MFT0 で次の操作を行う必要があります。
ドライバーは、パイプラインによって提供されるメタデータ バッファーにカスタム EXIF メタデータを提供します。 これは、サンプルが DevProxy に返されるときに、DevProxy によって MF_CAPTURE_METADATA_FRAME_RAWSTREAM IMFAttribute として MFSampleExtension_CaptureMetadata にアタッチされます。
MFT0 は、IMFSample を受け取ると、MF_CAPTURE_METADATA_FRAME_RAWSTREAM から生のメタデータ バッファーを取得し、カスタム EXIF メタデータ項目を解析して OEM で定義された IMFAttribute に変換し、MFSampleExtension_CaptureMetadata 属性バッグにアタッチします。
MFT0 から HW JPEG エンコーダーに EXIF データを渡すには、パイプライン写真シンクで次の処理が行われます。
IMFSample から MFSampleExtension_CaptureMetadata で GetUnknown を呼び出して、IMFSample を受信したときに属性バッグの IMFAttributes インターフェイスを取得します。
IPropertyBag2::Write を呼び出して、SampleMetadata で識別されるエンコーダー オプション プロパティを HW JPEG エンコーダーに設定します。 エンコーダー オプション プロパティには、前の手順で取得した IMFAttributes インターフェイスが含まれています。 このインターフェイスには、OEM EXIF サブ属性を含むすべてのカスタム サブ属性と、このトピックで前述した Metadata セクションの標準化されたサブ属性が含まれています。
さらなる処理のために EXIF データを取得するため、HW JPEG エンコーダーは次の処理を行います。
IPropertyBag2::Read を呼び出して、SampleMetadata プロパティ名と VT_UNKNOWN 型で識別されるプロパティのプロパティ値を取得します。 VARIANT.punkVal が返されると、MFSampleExtension_CaptureMetadata の IMFAttributes インターフェイスを受け取ります。
前の手順で取得したインターフェイスから OEM EXIF サブ属性で GetBlob または GetUnknown を呼び出し、OEM EXIF サブ属性の GUID とデータ型に基づいて EXIF データ BLOB を取得します。
サムネイル
カメラ ドライバーのサムネイルを生成するために MFT0 は必要ありません。 カメラ アプリは、独自にサムネイルを生成することが想定されます。 サムネイルは、写真確認の画像、HW JPEG エンコーダー、またはフルサイズの画像のサイズ変更から生成できます。 これは、アプリ開発者が決定します。 Windows 8.1 アプリとの API とアプリの互換性をメインするために、カメラ ドライバーは KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOTHUMBNAIL を実装してはなりません。
整数 ISO
KSPROPERTY_CAMERACONTROL_EXTENDED_ISO_ADVANCED プロパティ ID は、整数 ISO DDI に関連付けられている唯一のコントロールです。
高度なフォーカス
KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUSMODE プロパティ ID は、高度なフォーカス DDI に関連付けられている唯一のコントロールです。
Flash
KSPROPERTY_CAMERACONTROL_EXTENDED_FLASHMODE プロパティ ID は、フラッシュ DDI に関連付けられている唯一のコントロールです。
ズーム
KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM プロパティ ID は、ズーム DDI に関連付けられている唯一のコントロールです。
シーン モード
KSPROPERTY_CAMERACONTROL_EXTENDED_SCENEMODE プロパティ ID は、シーン モード DDI に関連付けられている唯一のコントロールです。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示