擷取統計資料後設資料屬性

下表總結了 MFT0 的 MFSampleExtension_CaptureMetaData 元數據屬性包中可用的擷取統計數據 IMFAttributes，適用於預覽、視訊和靜態擷取。

除非另有指示，否則每張所拍攝的靜態照片都必須具備列出的擷取統計數據。 針對預覽和視訊列出的擷取統計數據應盡最大努力提供，而驅動程式可能會或可能不會根據可用性和效能考慮在所有畫面上傳遞所有擷取統計數據。

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屬性包含擷取預覽畫面時測量的感測器讀取速率，其中包含高 32 位的分子值，以及低 32 位的分母值。

MF_CAPTURE_METADATA_FACEROIS

MF_CAPTURE_METADATA_FACEROIS屬性包含驅動程式偵測到的臉部矩形資訊。 根據預設，driver\MFT0 應該在預覽數據流上提供臉部資訊。 如果驅動程式在其他串流上公告功能，則如果應用程式在這些數據流上啟用臉部偵測，驅動程式\MFT 必須提供對應數據流上的臉部資訊。 當在驅動程式上啟用視訊防震時，應在完成影片防震後提供臉部資訊。 下列數據結構描述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 屬性具有 Count 字段的 FaceRectInfoBlobHeader 結構設定為零。）

MF_CAPTURE_METADATA_FACEROITIMESTAMPS

MF_CAPTURE_METADATA_FACEROITIMESTAMPS屬性包含MF_CAPTURE_METADATA_FACEROIS中所識別臉部感興趣區域的時間戳資訊。 對於無法提供臉部 ROIS 時間戳的裝置，應該省略此屬性。

下列數據結構描述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;

針對 [旗標] 字段，我們將定義下列位旗標，以指出哪個時間戳有效。 如果驅動程式提供臉部 ROIS 的時間戳元數據，MFT0 必須將 Flags 設定為 MF_METADATATIEMSTAMPS_DEVICE 和裝置的適當 QPC 時間。

#define MF_METADATATIMESTAMPS_DEVICE 0x00000001

#define MF_METADATATIMESTAMPS_PRESENTATION 0x00000002

請注意，MetadataTimeStamps 結構只會描述 MF_CAPTURE_METADATA_FACEROITIMESTAMPS 屬性的 Blob 格式。 時間戳的元數據項目結構（KSCAMERA_METADATA_ITEMHEADER + 時間戳元數據承載）由驅動程式決定，且必須對齊 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 中的 Face Attribute 項目數目和順序必須符合MF_CAPTURE_METADATA_FACEROIS blob 中 FaceRectInfo 專案的數目和順序。   每個臉部特徵項目都代表相同索引的對應 FaceRectInfo 項目中臉部的眨眼狀態或臉部表情狀態。

下圖說明臉部特徵 Blob 的版面配置，以及四個臉部 ROIs Blob 的版面配置，第一個臉部既不眨眼也不微笑，第二個眨左眼，第三個微笑，第四個臉部既眨眼（雙眼）又微笑。

MF_CAPTURE_METADATA_EXPOSURE_TIME

MF_CAPTURE_METADATA_EXPOSURE_TIME屬性包含在擷取預覽和\或相片畫面時套用至感測器的曝光時間，也就是 UINT64 且為 100ns。

捕捉元數據曝光補償

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屬性包含套用至所擷取相片的閃光燈功率，範圍為[0, 100]之間的值。 如果驅動程式不支援閃光燈的可調整電源，則應該省略這個屬性。

MF_CAPTURE_METADATA_WHITEBALANCE

MF_CAPTURE_METADATA_WHITEBALANCE屬性包含擷取預覽和\或相片框時套用至感測器的白色平衡，這是 Kevin 中的值。

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包含 EXIF 元數據，如第 3.1 節 （Blob 定義） 中所指定。 MFT0 需從驅動程式提供的 MF_CAPTURE_METADATA_FRAME_RAWSTREAM 緩衝區中擷取原始 EXIF 元數據，這被識別為自訂元數據項目（MetadataId >= MetadataId_Custom_Start）。 MFT0 接著會將原始數據轉換成MF_CAPTURE_METADATA_EXIF屬性。

Blob 定義

Blob 應包含完整的 TIFF 標頭、第 0 個 IFD 和 EXIF 子 IFD，如 EXIF 2.3 和 TIFF 6.0 規格所定義。 Blob 不應在 TIFF 標頭之前包含任何數據。 Blob 不應包含第 0 個 IFD 結尾之後的任何數據。 例如，包含縮圖數據的 IFD 無效。

下圖從 TIFF 規格複製，說明預期的記憶體配置：

以下是與 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 元數據。

選擇性/OEM 所定義的元數據

只要相機驅動程式符合 EXIF 規格，並儲存在第 0 個 TIFF IFD 或 EXIF 子 IFD 中，相機驅動程式可能會以自定義 EXIF 標記的形式包含任何其他元數據。

MakerNote 需求和二進位佈局規格

相機驅動程式可能包含製造商專屬資訊，以製作者註釋（標記 37500）的形式呈現。 製作者附註不能包含任何指向外部的指標，也不能依賴附註本身之外的數據，包括檔案的開頭和 TIFF 標頭的位置。 此外，它不得假設 TIFF 標頭中所指定之檔案的結束度。

一般而言，作業系統不保證元數據 blob 的二進位格式在寫入輸出 JPEG 數據流時保留不變。 它只會保證元數據是以符合 EXIF 規格的方式寫出。 例如，它只保證製作者附註會被複製為連續的區塊，並透過正確的 IFD 標籤、類型和偏移量來識別。

使用 WIC JPEG 編碼器

MF_CAPTURE_METADATA_EXIF 的預期使用方式是搭配作業系統提供的 Windows 映像處理元件 (WIC) JPEG 編碼器。 Windows 數位相機管線會使用 Windows WIC JPEG 編碼器來取用從 MF_CAPTURE_METADATA_EXIF取得的 EXIF 元數據，並在應用程式未直接從相機擷取 JPEG 時，將影像圖元數據多任務處理至 JPEG 檔案，但設定管線以擷取至 NV12/YUY2，並由 OS 編碼

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_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 中的每個直方圖都會由其專屬的直方圖標頭來識別。
3. 每個直方圖都有自己的區域和感測器輸出大小相關聯。 對於全畫幅直方圖，區域將符合 HistogramGrid 中指定的感測器輸出大小。
4. 所有可用通道的直方圖數據都會分組在一個直方圖下。 每個通道的直方圖數據是由位於數據上方的 HistogramDataHeader 識別的。 ChannelMasks 會指出有多少個通道和哪些通道具有直方圖數據，這是所支援MF_HISTOGRAM_CHANNEL_XXX位掩碼的位 OR，如上面所定義。 ChannelMask 會指出數據所針對的通道，這些數據是由上面定義的任何一個MF_HISTOGRAM_CHANNEL_XXX位掩碼所識別。

下圖說明直方圖區塊具有全幅 Y 直方圖的配置。

直方圖數據是ULONG的陣列，每個項目都代表一組由區間分類的色調值下的像素數量。 陣列中的數據應該從 bin 0 開始到 bin N-1，其中 N 是直方圖中的 bin 數目，也就是 HistogramBlobHeader.Bins。

下圖說明直方圖數據區段的配置。

下圖說明 YRGB 直方圖 Blob 的配置，此直方圖具有四個通道並採用完整框架。

下圖說明直方圖 Blob 的配置，其中包含僅限 Y 的直方圖，後面接著具有三個通道的 RGB 直方圖。

針對閾值，至少必須提供包含 Y 通道的完整幀直方圖，且該直方圖應是直方圖 Blob 中的第一個直方圖，前提是支援 KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM。

請注意，HistogramBlobHeader、HistogramHeader、HistogramDataHeader 和 Histogram 數據僅描述 MF_CAPTURE_METADATA_HISTOGRAM 屬性的 Blob 格式。 驅動程式決定直方圖的元數據項目結構（KSCAMERA_METADATA_ITEMHEADER + 所有直方圖的元數據承載），並且必須對齊 8 位元組。

直方圖元數據控制件

KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM 是屬性識別碼，將用來控制驅動程式所產生的直方圖元數據。 這是僅供預覽釘選使用的針腳層級控制，其定義如下：

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控件。

當預覽插釘的狀態高於 KSSTATE_STOP 時，此控制的 SET 呼叫將無效。 如果預覽狀態不是停止狀態，並傳回STATUS_INVALID_DEVICE_STATE，驅動程式應拒絕收到的SET呼叫。 在 GET 呼叫中，驅動程式應該會傳回 [旗標] 字段中的目前設定。

這是同步控制件。 此控制件沒有定義任何功能。

KSCAMERA_EXTENDEDPROP_HEADER

版本

必須是 1。

Pin識別碼

必須是與預覽的 Pin 相關聯的 Pin ID。

大小

必須是 sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VALUE)

結果

指出最後一個SET作業的錯誤結果。 如果沒有進行 SET 作業，這必須是 0。

能力

必須是 0。

標誌

這是讀取/寫入欄位。 這可以是上述任何一個 KSCAMERA_EXTENDEDPROP_HISTOGRAM_XXX 旗標。

KSCAMERA_EXTENDEDPROP_VALUE

未使用