次の方法で共有

統計メタデータ属性のキャプチャ

  • [アーティクル]

次の表は、MFT0 の MFSampleExtension_CaptureMetaData メタデータ属性バッグで使用できるキャプチャ統計 IMFAttributes を、プレビュー、ビデオ、静止画キャプチャ用にまとめたものです。

静止画に記載されているキャプチャ統計は、特に明記されていない限り、キャプチャされたすべての写真に対して必須です。 プレビューとビデオに記載されているキャプチャ統計は、ベスト エフォートとして配信する必要があります。ドライバーは、可用性とパフォーマンスの考慮事項に基づいて、すべてのフレームですべてのキャプチャ統計を配信する場合と配信しない場合があります。

名前 Type ピン留めする 説明
MF_CAPTURE_METADATA_FOCUSSTATE UINT32 プレビュー この属性には現在のフォーカス状態が含まれ、次の値のいずれかを使用できます。
MF_CAPTURE_METADATA_SENSORFRAMERATE UINT64 プレビュー この属性には、プレビュー フレームがキャプチャされたときに測定されたセンサーの読み出しレートが含まれます (Hz 単位)。分子の値が上位 32 ビットで、分母の値が下位 32 ビットで構成されます。
MF_CAPTURE_METADATA_FACEROIS BLOB プレビュー、ビデオ この属性には、ドライバーによる顔検出の四角形の情報が含まれます。
MF_CAPTURE_METADATA_FACEROITIMESTAMPS BLOB プレビュー、ビデオ この属性には、MF_CAPTURE_METADATA_FACEROIS で識別された顔 ROI のタイム スタンプ情報が含まれます。
MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS BLOB プレビュー、ビデオ この属性には、MF_CAPTURE_METADATA_FACEROIS で識別された顔 ROI のまばたきと表情の状態が含まれます。 
MF_CAPTURE_METADATA_EXPOSURE_TIME UINT64 プレビュー、静止画 この属性には、100 ナノ秒で適用される露光時間が含まれます
MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION BLOB プレビュー、静止画 この属性には、EV 補正ステップ フラグと、写真のキャプチャ時にドライバーに適用されたステップ単位の EV 補正値が含まれます。
MF_CAPTURE_METADATA_ISO_SPEED UINT32 プレビュー、静止画 この属性には、整数として適用される ISO 感度値が含まれます。
MF_CAPTURE_METADATA_LENS_POSITION UINT32 プレビュー、静止画 この属性には、キャプチャされた写真にフォーカスが適用されたときの論理的なレンズ位置が含まれます。 この値には、特定の単位がありません。
MF_CAPTURE_METADATA_SCENE_MODE UINT64 静止画 この属性には、UINT64KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX フラグとして適用されるシーン モードが含まれます。
MF_CAPTURE_METADATA_FLASH UINT32 (ブール値) プレビュー、静止画 この属性には、フラッシュ状態を含むブール値が含まれています。 値 1 はキャプチャされた写真のフラッシュがオン、値 0 はフラッシュがオフであることを指定します。
MF_CAPTURE_METADATA_FLASH_POWER UINT32 静止画 [省略可能] この属性には、0～100 のパーセンテージ値として適用するフラッシュ出力が含まれます。
MF_CAPTURE_METADATA_WHITEBALANCE UINT32 (ケルビン) プレビュー、静止画 この属性には、ケルビン値として適用するホワイト バランスが含まれます。
MF_CAPTURE_METADATA_ZOOMFACTOR UINT32 (Q16) 静止画 この属性には、適用したズーム値が含まれており、Get 呼び出しで KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM からクエリを実行できる値と同じです。 値は Q16 である必要があります
MF_CAPTURE_METADATA_EXIF BLOB 静止画 [省略可能] この属性には、BLOB 定義セクション で指定された EXIF メタデータが含まれます。
MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID UINT32 静止画 [省略可能] この属性には、可変写真シーケンス内の対応するフレームのフレーム ID が含まれます。 この属性は、可変写真シーケンスのキャプチャに対してのみ設定されます。
MF_CAPTURE_METADATA_ISO_GAINS BLOB プレビュー この属性には、プレビュー フレームのキャプチャ時にセンサーに適用されるアナログとデジタルのゲインが含まれます。 これには単位がありません。
MF_CAPTURE_METADATA_WHITEBALANCE_GAINS BLOB プレビュー この属性には、プレビュー フレームのキャプチャ時にセンサーと ISP によって R、G、B に適用されるホワイト バランスゲインが含まれます。 これには単位がありません。
MF_CAPTURE_METADATA_HISTOGRAM BLOB プレビュー この属性には、プレビュー フレームがキャプチャされたときのヒストグラムが含まれます。
MF_CAPTURE_METADATA_FRAME_ILLUMINATION UINT64 Hello に使用される IR ピン この属性は IR カメラ用で、フレームがアクティブな IR 照明を使用しているかどうかを指定し、FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION と組み合わせて使用する必要があります。
任意のカスタム GUID 任意のバリアント型 この属性には、カスタム GUID に関連付けられているカスタム データが含まれています

MF_CAPTURE_METADATA_FOCUSSTATE

MF_CAPTURE_METADATA_FOCUSSTATE 属性には、現在のフォーカス状態が含まれており、次のいずれかの値を使用できます。

typedef enum
{
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_UNINITIALIZED = 0,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_LOST,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_SEARCHING,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_FOCUSED,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_FAILED,
} KSCAMERA_EXTENDEDPROP_FOCUSSTATE;

MF_CAPTURE_METADATA_SENSORFRAMERATE

MF_CAPTURE_METADATA_SENSORFRAMERATE 属性には、プレビュー フレームのキャプチャ時に測定されたセンサー読み取り率が含まれます (Hz 単位)。これは、分子が上位 32 ビットで、分母が下位 32 ビットで構成されます。

MF_CAPTURE_METADATA_FACEROIS

MF_CAPTURE_METADATA_FACEROIS 属性には、ドライバーによる顔検出の四角形の情報が含まれます。 デフォルトでは、driver\MFT0 はプレビュー ストリームの顔情報を提供する必要があります。 ドライバーが他のストリームで機能を公開する場合、アプリケーションがそれらのストリームで顔検出を有効にすれば、driver\MFT は対応するストリームで顔情報を提供する必要があります。 ドライバーの Video Stabilization が有効になっている場合、Video Stabilization 後に顔情報を提供する必要があります。 以下のデータ構造体は、MF_CAPTURE_METADATA_FACEROIS の BLOB 形式を表しています。 目立つ顔は、BLOB 内の最初の FaceRectInfo である必要があります。

typedef struct tagFaceRectInfoBlobHeader
{
    ULONG Size;             // Size of this header + all FaceRectInfo following
    ULONG Count;            // Number of FaceRectInfo’s in the blob
} FaceRectInfoBlobHeader;

typedef struct tagFaceRectInfo
{
    RECT Region;            // Relative coordinates on the frame that face detection is running (Q31 format)
    LONG ConfidenceLevel;   // Confidence level of the region being a face ([0, 100])
} FaceRectInfo;

FaceRectinfoBlobHeader 構造体と FaceRectInfo 構造体は、MF_CAPTURE_METADATA_FACEROIS 属性の BLOB 形式のみを表すことに注意してください。 顔 ROI のメタデータ項目の構造体 (KSCAMERA_METADATA_ITEMHEADER + 顔 ROI メタデータ ペイロード) は、ドライバーによって決まりますが、8 バイトでアラインされている必要があります。

設計上、顔検出が有効なストリームが構成され、キャプチャ中に問題のシーンに顔が含まれない場合、ドライバーは、顔情報が関連付けられていない各サンプルに「ダミー」の MF_CAPTURE_METADATA_FACEROIS 属性をアタッチする必要があります。 (「ダミー」の顔 ROI 属性では、FaceRectInfoBlobHeader 構造体の [Count] フィールドが 0 に設定されています)。

MF_CAPTURE_METADATA_FACEROITIMESTAMPS

MF_CAPTURE_METADATA_FACEROITIMESTAMPS 属性には、MF_CAPTURE_METADATA_FACEROIS で識別された顔 ROI のタイム スタンプ情報が含まれます。 顔 ROI のタイム スタンプを提供できないデバイスの場合は、この属性を省略する必要があります。

以下のデータ構造体は、MF_CAPTURE_METADATA_FACEROITIMESTAMPS の BLOB 形式を表しています。

typedef struct tagMetadataTimeStamps
{
    ULONG Flags;            // Bitwise OR of MF_METADATATIMESTAMPS_XXX flags
    LONGLONG Device;        // QPC time for the sample where the face rect is derived from (in 100ns)
    LONGLONG Presentation;  // PTS for the sample where the face rect is derived from (in 100ns)
} MetadataTimeStamps;

[Flags] フィールドでは、有効なタイム スタンプを示すために、次のビット フラグを定義します。 ドライバーによって顔 ROI のタイム スタンプ メタデータを提供する場合、MFT0 は Flags を MF_METADATATIEMSTAMPS_DEVICE に設定し、デバイスの適切な QPC 時間を設定する必要があります。

#define MF_METADATATIMESTAMPS_DEVICE 0x00000001

#define MF_METADATATIMESTAMPS_PRESENTATION 0x00000002

MetadataTimeStamps 構造体は、MF_CAPTURE_METADATA_FACEROITIMESTAMPS 属性の BLOB 形式のみを表すことに注意してください。 timestamp のメタデータ項目の構造体 (KSCAMERA_METADATA_ITEMHEADER + timestamp メタデータ ペイロード) は、ドライバーによって決まりますが、8 バイトでアラインされている必要があります。

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS 属性には、MF_CAPTURE_METADATA_FACEROIS で識別された顔 ROI のまばたきと顔の表情の状態が含まれます。  まばたきや表情の検出をサポートしていないデバイスの場合、この属性は省略する必要があります。

以下のデータ構造体は、MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS の BLOB 形式を表しています。

FaceCharacterizationBlobHeader 構造体と FaceCharacterization 構造体は、MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS 属性の BLOB 形式のみを表すことに注意してください。 顔特性メタデータ項目の構造体 (KSCAMERA_METADATA_ITEMHEADER + 顔特性メタデータ ペイロード) は、ドライバーによって決まりますが、8 バイトでアラインされている必要があります。

typedef struct tagFaceCharacterizationBlobHeader
{
    ULONG Size;     // Size of this header + all FaceCharacterization following
    ULONG Count;    // Number of FaceCharacterization’s in the blob. Must match the number of FaceRectInfo’s in FaceRectInfoBlobHeader
} FaceCharacterizationBlobHeader;

typedef struct tagFaceCharacterization
{
    ULONG BlinkScoreLeft;   // [0, 100]. 0 indicates no blink for the left eye. 100 indicates definite blink for the left eye
    ULONG BlinkScoreRight;  // [0, 100]. 0 indicates no blink for the right eye. 100 indicates definite blink for the right eye
    ULONG FacialExpression; // Any one of the MF_METADATAFACIALEXPRESSION_XXX defined
    ULONG FacialExpressionScore; // [0, 100]. 0 indicates no such facial expression as identified. 100 indicates definite such facial expression as defined
} FaceCharacterization;

検出可能な顔の表情を以下に定義します。  

#define MF_METADATAFACIALEXPRESSION_SMILE             0x00000001

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS 属性が存在する場合、その BLOB 内の FaceCharacterization エントリの数と順序は、MF_CAPTURE_METADATA_FACEROIS の BLOB 内の FaceRectInfo エントリの数と順序と一致する必要があります。   各 FaceCharacterization エントリは、同じインデックスにある対応する FaceRectInfo エントリ内のまばたきや顔の表情の状態を表します。

次の図は、4 つの顔 (1 人目はまばたきも笑顔もなし、2 人目は左目をまばたき、3 人目は笑顔、4 人目はまばたき (両目) と笑顔の両方) の、顔特性 BLOB と顔 ROI BLOB のレイアウトを示しています。

MF_CAPTURE_METADATA_EXPOSURE_TIME

MF_CAPTURE_METADATA_EXPOSURE_TIME 属性には、プレビューとフォト フレームがキャプチャされたときにセンサーに適用された露光時間が含まれます。これは UINT64 で、100ns です。

MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION

MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION 属性には、プレビューや写真フレームのキャプチャ時にセンサーに適用されたステップの単位で、EV 補正ステップ フラグと EV 補正値が含まれます。

以下のデータ構造体は、MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION の BLOB 形式を表しています。

typedef struct tagCapturedMetadataExposureCompensation
{
    UINT64 Flags;   // KSCAMERA_EXTENDEDPROP_EVCOMP_XXX step flag
    INT32 Value;    // EV Compensation value in units of the step
} CapturedMetadataExposureCompensation;

CapturedMetadataExposureCompensation 構造体では、MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION 属性の BLOB 形式のみを表すことに注意してください。 EV 補正メタデータ項目の構造体 (KSCAMERA_METADATA_ITEMHEADER + EV 補正メタデータ ペイロード) は、ドライバーによって決まりますが、8 バイトでアラインされている必要があります。

MF_CAPTURE_METADATA_ISO_SPEED

MF_CAPTURE_METADATA_ISO_SPEED 属性には、プレビューや写真フレームのキャプチャ時にセンサーに適用される ISO 感度値が含まれます。 これには単位がありません。

MF_CAPTURE_METADATA_ISO_GAINS

MF_CAPTURE_METADATA_ISO_GAINS 属性には、プレビュー フレームのキャプチャ時にセンサーに適用されるアナログとデジタルのゲインが含まれます。 これには単位がありません。

以下のデータ構造体は、MF_CAPTURE_METADATA_ISO_GAINS の BLOB 形式を表しています。

typedef struct tagCapturedMetadataISOGains
{
    FLOAT AnalogGain;
    FLOAT DigitalGain;
} CapturedMetadataISOGains;

CapturedMetadataISOGains 構造体では、MF_CAPTURE_METADATA_ISO_GAINS 属性の BLOB 形式のみを表すことに注意してください。 ISO ゲインのメタデータ項目の構造体 (KSCAMERA_METADATA_ITEMHEADER + ISO ゲイン メタデータ ペイロード) は、ドライバーによって決まりますが、8 バイトでアラインされている必要があります。

MF_CAPTURE_METADATA_LENS_POSITION

MF_CAPTURE_METADATA_LENS_POSITION 属性には、プレビュー フレームや写真フレームがキャプチャされたときの論理レンズ位置が含まれます。これには、単位はありません。 これは、GET 呼び出しの KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS からクエリできる値と同じです。

MF_CAPTURE_METADATA_SCENE_MODE

MF_CAPTURE_METADATA_SCENE_MODE 属性には、キャプチャされた写真に適用されるシーン モード (64 ビット KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX フラグ) が含まれます。

MF_CAPTURE_METADATA_FLASH

MF_CAPTURE_METADATA_FLASH 属性には、プレビューまたは写真フレームがキャプチャされたときのブール値が含まれます。1 はフラッシュ オン、0 はフラッシュ オフを表します。

MF_CAPTURE_METADATA_FLASH_POWER

MF_CAPTURE_METADATA_FLASH_POWER 属性には、[0, 100] の範囲の値であるキャプチャされた写真に適用されるフラッシュ出力が含まれます。 ドライバーがフラッシュの出力調整をサポートしていない場合は、この属性を省略する必要があります。

MF_CAPTURE_METADATA_WHITEBALANCE

MF_CAPTURE_METADATA_WHITEBALANCE 属性には、プレビューや写真フレームがキャプチャされたときにセンサーに適用されるホワイト バランスが含まれます。この値はケルビンで表します。

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS 属性には、プレビュー フレームのキャプチャ時にセンサーおよび ISP によって R、G、B に適用されるホワイト バランスのゲインが含まれます。 これには単位がありません。

以下のデータ構造体は、MF_CAPTURE_METADATA_WHITEBALANCE_GAINS の BLOB 形式を表しています。

typedef struct tagCapturedMetadataWhiteBalanceGains
{
    FLOAT R;
    FLOAT G;
    FLOAT B;
} CapturedMetadataWhiteBalanceGains;

CapturedMetadataWhiteBalanceGains 構造体では、MF_CAPTURE_METADATA_WHITEBALANCE_GAINS 属性の BLOB 形式のみを表すことに注意してください。 ホワイト バランス ゲインのメタデータ項目の構造体 (KSCAMERA_METADATA_ITEMHEADER + ホワイト バランス ゲインのメタデータ ペイロード) は、ドライバーによって決まりますが、8 バイトでアラインされている必要があります。

MF_CAPTURE_METADATA_ZOOMFACTOR

MF_CAPTURE_METADATA_ZOOMFACTOR 属性には、キャプチャされた写真に適用されるズーム値が含まれています。これは、GET 呼び出しで KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM からクエリできるのと同じ値です。 これは Q16 にある必要があります。

MF_CAPTURE_METADATA_EXIF

MF_CAPTURE_METADATA_EXIF には、セクション 3.1 (BLOB 定義) で指定されている EXIF メタデータが含まれます。 MFT0 は、ドライバーによって提供される MF_CAPTURE_METADATA_FRAME_RAWSTREAM バッファーから、カスタム メタデータ項目 (MetadataId >= MetadataId_Custom_Start) として識別される生の EXIF メタデータを抽出します。 その後、MFT0 は生データを MF_CAPTURE_METADATA_EXIF 属性に変換します。

BLOB の定義

BLOB は、EXIF 2.3 および TIFF 6.0 仕様で定義され、完全な TIFF ヘッダー、0 番目の IFD と EXIF サブ IFD で構成される必要があります。 BLOB には、TIFF ヘッダーの前にデータを含めないようにする必要があります。 BLOB には、0 番目の IFD の終了後にデータを含めないようにする必要があります。 たとえば、サムネイル データを含む IFD は無効です。

次の図は、TIFF の仕様からコピーしたもので、想定されるメモリ レイアウトを示しています。

EXIF blob definition.

次のものは、EXIF と TIFF の仕様と一致するが、強調のために呼び出された要件です。

  • バイトの順序は、リトル エンディアン ("II") またはビッグ エンディアン ("MM") のいずれかになります。
  • ポインター (TIFF 仕様では「バイト オフセット」) は、TIFF ヘッダーの先頭を基準とします。

以下は、EXIF と TIFF 仕様よりも制限の厳しい要件です。

  • 次の IFD へのオフセットは 0 である必要があります。つまり、追加の IFD は示されません。
  • TIFF ヘッダーと 0 番目の IFD は連続している必要があります。つまり、バイト 4～7 に格納される 0 番目の IFD へのオフセットは 0x8 である必要があります。

必須の EXIF メタデータ

以下のセクションでは、MF_CAPTURE_METADATA_EXIF に含める必要がある EXIF メタデータについて説明します。

名前 EXIF タグ 説明
オリエンテーション 274 行と列で見た画像の向き。 詳細については、EXIF 仕様を参照してください
製造業者 271 録音機器のメーカー
モデル 272 デバイスのモデル名またはモデル番号
XResolution 282 ImageWidth 方向の解像度単位あたりのピクセル数
YResolution 283 ImageLength 方向の解像度単位あたりのピクセル数
ResolutionUnit 296 XResolution および YResolution を測定する単位
ソフトウェア 305 ファームウェアの名前とバージョン
ColorSpace 40961 色空間の情報 (通常は sRGB)
SubsSecTimeOriginal 37521 DateTimeOriginal タグに関連する小数点以下の秒数を記録します。
SubSecTimeDigitized 37522 DateTimeDigitized タグに関連付けられた小数点以下の秒数を記録します
ExposureTime 33434 露出時間 (秒) (0.001 秒の精度)
FNumber 33437 キャプチャに使用される F 値
ISOSpeedRatings 34855 ISO 12322 で定義されている ISO 感度値、彩度ベース
DateTimeOriginal 36867 元の画像データが生成された日時
DateTimeDIgitized 36868 画像がデジタル データとして保存された日時
シャッター SpeedValue 37377 APEX (Additive System of Photographic Exposure) 単位でのシャッター スピード。
口径値 37378 レンズ口径 (APEX 単位)
ExposureBias 値 37380 露出バイアス値 (APEX 単位)
MeteringMode 37383 AE 測定モード (EXIF 仕様を参照)
LightSource 37384 光源の種類 (EXIF 仕様を参照)
Flash 37385 イメージ キャプチャ中のフラッシュの状態
FocalLength 37386 レンズの実際の焦点距離
ExposureMode 41986 キャプチャ中の露出モード
WhiteBalance 41987 キャプチャ中のホワイト バランス モード
DigitalZoomRatio 41988 画像キャプチャ中のデジタル ズーム倍率
FocalLengthIn35mmFilm 41989 35 mm 相当の焦点距離
SceneCaptureType 41990 撮影されたシーンの種類

省略可能/OEM で定義されたメタデータ

カメラ ドライバーは、EXIF 仕様に準拠し、0 番目の TIFF IFD または EXIF サブ IFD のいずれかに格納されている限り、カスタム EXIF タグの形式で任意の追加メタデータを含めることができます。

MakerNote の要件とバイナリ レイアウトの想定

カメラ ドライバーには、メーカー独自の情報をメーカー ノート (タグ 37500) の形式で含めることができます。 メーカー ノートは、ファイルの開始位置や TIFF ヘッダーの位置など、メーカー ノート自体の外部にあるデータへのポインターを含めたり、これに依存したりすることはできません。 さらに、TIFF ヘッダーで指定されているファイルのエンディアンを想定することはできません。

一般に、オペレーティング システムでは、メタデータ BLOB が出力 JPEG ストリームに書き込まれるとき、メタデータ BLOB のバイナリ レイアウトが保持されることを保証しません。 メタデータが EXIF 仕様に準拠して書き出されることに限って保証します。 たとえば、メーカー ノートが連続したブロックとしてコピーされ、正しい IFD タグ、タイプ、オフセットによって識別されることのみを保証します。

WIC JPEG エンコーダーでの使用

MF_CAPTURE_METADATA_EXIF の使用目的は、OS が提供する Windows Imaging Component (WIC) JPEG エンコーダーを使用することです。 Windows Camera パイプラインでは、アプリケーションによってカメラから直接 JPEG をキャプチャするのではなく、NV12/YUY2 にキャプチャし、OS によってエンコードされるようにパイプラインが設定されている場合、Windows WIC JPEG エンコーダーを使用して、MF_CAPTURE_METADATA_EXIF から取得した EXIF メタデータを使用して、画像ピクセル データを JPEG ファイルに多重化します。

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID 属性には、可変写真シーケンス内の対応するフレームのフレーム ID が含まれます。 この属性は、可変写真シーケンスのキャプチャに対してのみ設定されます。

MF_CAPTURE_METADATA_FRAME_ILLUMINATION

IR カメラの MF_CAPTURE_METADATA_FRAME_ILLUMINATION 属性は、フレームがアクティブな IR 照明を使用しているかどうかを指定し、FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION と組み合わせて使用する必要があります。 これは IR サンプルにのみ使用されます。カメラが IR サンプルとカラー サンプルの両方をサポートしている場合、RGB フレームには存在しません。

アクティブな照明がオンのときにフレームがキャプチャされた場合は値を 0xXXXXXXXXXXXXXXX1 に設定し、フレームのキャプチャ時に照明が存在しない場合は 0xXXXXXXXXXXXXXXX0 に設定する必要があります。

MF_CAPTURE_METADATA_HISTOGRAM

MF_CAPTURE_METADATA_HISTOGRAM 属性には、プレビュー フレームがキャプチャされたときのヒストグラムが含まれます。

以下のデータ構造体は、MF_CAPTURE_METADATA_HISTOGRAM の BLOB 形式を表しています。

typedef struct tagHistogramGrid
{
    ULONG Width;    // Width of the sensor output that histogram is collected from
    ULONG Height;   // Height of the sensor output that histogram is collected from
    RECT Region;    // Absolute coordinates of the region on the sensor output that the histogram is collected for
} HistogramGrid;

typedef struct tagHistogramBlobHeader
{
    ULONG Size;         // Size of the entire histogram blob in bytes
    ULONG Histograms;   // Number of histograms in the blob. Each histogram is identified by a HistogramHeader
} HistogramBlobHeader;

typedef struct tagHistogramHeader
{
    ULONG Size;         // Size of this header + (HistogramDataHeader + histogram data following) * number of channels available
    ULONG Bins;         // Number of bins in the histogram
    ULONG FourCC;       // Color space that the histogram is collected from
    ULONG ChannelMasks; // Masks of the color channels that the histogram is collected for
    HistogramGrid Grid; // Grid that the histogram is collected from
} HistogramHeader;

typedef struct tagHistogramDataHeader
{
    ULONG Size;         // Size in bytes of this header + histogram data following
    ULONG ChannelMask;  // Mask of the color channel for the histogram data
    ULONG Linear;       // 1, if linear; 0 nonlinear
} HistogramDataHeader;

[ChannelMasks] フィールドの場合、ヒストグラムで使用可能なチャネルを示すために、次のビットマスクを定義します。

#define MF_HISTOGRAM_CHANNEL_Y  0x00000001
#define MF_HISTOGRAM_CHANNEL_R  0x00000002
#define MF_HISTOGRAM_CHANNEL_G  0x00000004
#define MF_HISTOGRAM_CHANNEL_B  0x00000008
#define MF_HISTOGRAM_CHANNEL_Cb 0x00000010
#define MF_HISTOGRAM_CHANNEL_Cr 0x00000020

注:

  1. 各 BLOB には、同じフレームの異なる領域または異なる色空間から収集された複数のヒストグラムを含めることができます。
  2. BLOB 内の各ヒストグラムは、独自の HistogramHeader によって識別されます。
  3. 各ヒストグラムには、独自の領域とセンサー出力サイズが関連付けられています。 フル フレームのヒストグラムの場合、領域は HistogramGrid で指定されたセンサー出力サイズと一致します。
  4. 使用可能なすべてのチャネルのヒストグラム データは、1 つのヒストグラムの下にグループ化されます。 各チャネルのヒストグラム データは、データのすぐ上にある HistogramDataHeader によって識別されます。 ChannelMasks は、ヒストグラム データを持つチャネルの数とチャネルを示します。これは、上記で定義した MF_HISTOGRAM_CHANNEL_XXX ビットマスクのビット OR です。 ChannelMask は、データの対象となるチャネルを示します。これは、上記で定義した MF_HISTOGRAM_CHANNEL_XXX ビットマスクのいずれかによって識別されます。

次の図は、フル フレームの Y のみのヒストグラムを持つヒストグラム BLOB のレイアウトを示しています。

ヒストグラム データは ULONG の配列で、各エントリはビンで分類された一連の色調値に該当するピクセルの数を表します。 配列のデータは bin 0 から始まり bin N-1 までです。N はヒストグラムのビンの数 (HistogramBlobHeader.Bins) です。

次の図は、ヒストグラム データ セクションのレイアウトを示しています。

次の図は、4 つのチャネルを持つフル フレームの YRGB ヒストグラムを含むヒストグラム BLOB のレイアウトを示しています。

次の図は、Y のみのヒストグラムの後に 3 つのチャネルを含む RGB ヒストグラムが続くヒストグラム BLOB のレイアウトを示しています。

しきい値の場合、少なくとも Y チャネルを持つフル フレーム ヒストグラムを指定する必要があります。これは、KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM がサポートされている場合は、ヒストグラム BLOB の最初のヒストグラムである必要があります。

HistogramBlobHeader、HistogramHeader、HistogramDataHeader、Histogram データでは、MF_CAPTURE_METADATA_HISTOGRAM 属性の BLOB 形式のみを表すことに注意してください。 ヒストグラムのメタデータ項目の構造体 (KSCAMERA_METADATA_ITEMHEADER + すべてのヒストグラム メタデータ ペイロード) は、ドライバーによって決まりますが、8 バイトでアラインされている必要があります。

ヒストグラム メタデータ コントロール

KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM は、ドライバーによって生成されるヒストグラム メタデータを制御するために使用されるプロパティ ID です。 これはプレビュー ピンのみのピン レベル コントロールで、次のように定義されています。

typedef enum {
    …
#if (NTDDI_VERSION >= NTDDI_WIN8)
    KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM
#endif
} KSPROPERTY_CAMERACONTROL_EXTENDED_PROPERTY;

KSCAMERA_EXTENDEDPROP_HEADER では、ドライバーのヒストグラム メタデータを制御するために、次のビット フラグを定義します。 既定値は OFF です。

#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_OFF 0x0000000000000000
#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_ON  0x0000000000000001

KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA コントロールの前にこのコントロールを使用して、適切なサイズのメタデータ バッファーが割り当てられていることを確認する必要があります。

HISTOGRAM_OFF に設定されている場合、ドライバーはプレビュー ピンでヒストグラム メタデータを配信しません。 ドライバーは、メタデータ バッファー サイズ要件にヒストグラム メタデータ サイズを含めないでください。

HISTOGRAM_ON に設定されている場合、ドライバーはプレビュー ピンでヒストグラム メタデータを配信します。 ドライバーは、メタデータ バッファー サイズ要件にヒストグラム メタデータ サイズを含める必要があります。

ドライバーにヒストグラム メタデータを生成する機能がない場合、ドライバーはこのコントロールを実装しないでください。 ドライバーがこのコントロールをサポートしている場合は、KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA コントロールもサポートする必要があります。

このコントロールの SET 呼び出しは、プレビュー ピンが KSSTATE_STOP 状態より高い状態の場合は影響しません。 ドライバーは、プレビューが停止状態でない場合に受信した SET 呼び出しを拒否し、STATUS_INVALID_DEVICE_STATE を返します。 GET 呼び出しでは、ドライバーが [Flags] フィールドの現在の設定を返す必要があります。

これは同期コントロールです。 このコントロールには機能が定義されていません。

KSCAMERA_EXTENDEDPROP_HEADER

バージョン

1 にする必要があります。

PinId

写真ピンに関連付けられているプレビュー ID である必要があります。

サイズ

`Default` である必要があります。

結果

最後の SET 操作のエラー結果を示します。 SET 操作が実行されていない場合は、0 にする必要があります。

機能

0 を指定する必要があります。

Flags

これは読み取り/書き込みフィールドです。 これは、上記で定義した任意の KSCAMERA_EXTENDEDPROP_HISTOGRAM_XXX フラグです。

KSCAMERA_EXTENDEDPROP_VALUE

非使用