捕获统计信息元数据属性

下表汇总了 MFT0 的用于预览、视频和静态捕获的 MFSampleExtension_CaptureMetaData 元数据属性包的可用捕获统计信息 IMFAttributes。

除非另有说明，否则对于拍摄的每张照片，仍必须提供为 列出的捕获统计信息。 为预览和视频列出的捕获统计信息应尽最大努力提供，驱动程序可能会也可能不会根据可用性和性能注意事项在所有帧上提供所有捕获统计信息。

名称	类型	Pin	说明
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中标识的人脸的 blink 和\或面部表情状态。
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 (开尔文)	预览，仍然	此属性包含以 Kelvin 表示的值应用的白平衡。
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	预览	在捕获preview 帧时，此属性包含直方图。
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 属性包含捕获预览帧时测量的传感器读出速率（以赫为单位），该帧包含高 32 位中的分子值和低 32 位中的分母值。

MF_CAPTURE_METADATA_FACEROIS

MF_CAPTURE_METADATA_FACEROIS 属性包含驱动程序检测到的人脸矩形信息。 默认情况下，driver\MFT0 应提供预览流中的人脸信息。 如果驱动程序在其他流上播发该功能，则如果应用程序在这些流上启用人脸检测，则 driver\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 格式。 人脸 ROIs (KSCAMERA_METADATA_ITEMHEADER + 人脸 ROIs 元数据有效负载) 的元数据项结构由驱动程序决定，并且必须对齐 8 字节。

根据设计，如果配置了启用了人脸检测的流，并且相关场景在捕获过程中不包含任何人脸，则驱动程序仍需要将“虚拟”MF_CAPTURE_METADATA_FACEROIS属性附加到每个没有与之关联的人脸信息的示例。 (“虚拟”人脸 ROI 属性的 FaceRectInfoBlobHeader 结构的 Count 字段设置为零。)

MF_CAPTURE_METADATA_FACEROITIMESTAMPS

MF_CAPTURE_METADATA_FACEROITIMESTAMPS 属性包含MF_CAPTURE_METADATA_FACEROIS中标识的人脸 ROIs 的时间戳信息。 对于无法为人脸 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 必须将标志设置为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 格式。

请注意，FaceTraitsBlobHeader 和 FaceTraits 结构仅描述 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 描述项的数量和顺序必须与 MF_CAPTURE_METADATA_FACEROIS blob 中 FaceRectInfo 条目的数量和顺序匹配。   每个 FaceCharacterization 条目表示同一索引处相应 FaceRectInfo 条目中人脸的闪烁和面部表情状态。

下图演示了人脸特征 blob 和四张人脸的 ROIs 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 属性包含捕获预览和/或相框时应用于传感器的白平衡，这是 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包含第 3.1 节 (Blob 定义) 中指定的 EXIF 元数据。 MFT0 应从驱动程序提供的 MF_CAPTURE_METADATA_FRAME_RAWSTREAM 缓冲区中提取原始 EXIF 元数据，该元数据标识为自定义元数据项 (MetadataId >= MetadataId_Custom_Start) 。 MFT0 随后应将原始数据转换为MF_CAPTURE_METADATA_EXIF属性。

Blob 定义

Blob 应包含 EXIF 2.3 和 TIFF 6.0 规范所定义的完整的 TIFF 标头、第 0 个 IFD 和 EXIF 子 IFD。 Blob 不应在 TIFF 标头之前包含任何数据。 第 0 个 IFD 结束后，Blob 不应包含任何数据。 例如，包含包含缩略图数据的 IFD 无效。

下图从 TIFF 规范复制，说明了预期的内存布局：

以下是与 EXIF 和 TIFF 规范一致但强调的要求：

• 字节顺序应为 little endian (“II”) 或 big endian (“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	存储为数字数据的映像的日期和时间
Shutter SpeedValue	37377	摄影曝光附加系统中的快门速度 (APEX) 单位
光圈值	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 流时保留。 它仅保证元数据的写出符合 EXIF 规范。 例如，它仅保证将制作者备注复制为连续块，并由正确的 IFD 标记、类型和偏移量标识。

与 WIC JPEG 编码器配合使用

MF_CAPTURE_METADATA_EXIF的预期用途是使用操作系统提供的 Windows 映像组件 (WIC) JPEG 编码器。 Windows 相机管道使用 Windows WIC JPEG 编码器来使用从MF_CAPTURE_METADATA_EXIF获取的 EXIF 元数据，并在应用程序未直接从相机捕获 JPEG，而是将管道配置为捕获到 NV12/YUY2 并由 OS 编码时，将图像像素数据与图像像素数据复用到 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 帧上。

如果启用活动照明时捕获帧，则值应设置为 0xXXXXXXXXXXXXXXXXXX1;如果捕获帧时没有照明，则值应设置为 0xXXXXXXXXXXXXXXXXXX0。

MF_CAPTURE_METADATA_HISTOGRAM

MF_CAPTURE_METADATA_HISTOGRAM 属性包含捕获preview 帧时的直方图。

以下数据结构描述了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 中的每个直方图由其自己的直方图Header 标识
3. 每个直方图都有自己的区域和关联的传感器输出大小。 对于全帧直方图，该区域将与 HistogramGrid 中指定的传感器输出大小匹配。
4. 所有可用通道的直方图数据都分组在一个直方图下。 每个通道的直方图数据由数据上方的 HistogramDataHeader 标识。 ChannelMask 指示有多少通道以及哪些通道具有直方图数据，即上面定义的受支持MF_HISTOGRAM_CHANNEL_XXX位掩码的按位 OR。 ChannelMask 指示数据所针对的通道，该通道由上面定义的任一MF_HISTOGRAM_CHANNEL_XXX位掩码标识。

下图演示了具有全帧 Y 型直方图的直方图 Blob 的布局。

直方图数据是 ULONG 数组，每个条目表示一组音调值下按箱分类的像素数。 数组中的数据应从 bin 0 开始到 bin N-1，其中 N 是直方图中的箱数，即 HistogramBlobHeader.Bins。

下图演示了直方图数据部分的布局。

下图演示了具有四个通道的全帧 YRGB 直方图的直方图 Blob 的布局。

下图演示了一个直方图 Blob 的布局，该 Blob 具有仅限 Y 的直方图，后跟具有三个通道的 RGB 直方图。

对于“阈值”，至少必须提供具有 Y 通道的全帧直方图，如果支持KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM，该直方图应是直方图 blob 中的第一个直方图。

请注意，HistogramBlobHeader、HistogramHeader、HistogramDataHeader 和直方图数据仅描述 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控件。

当预览引脚处于高于KSSTATE_STOP状态的任一状态时，此控件的 SET 调用不起作用。 如果预览未处于停止状态，驱动程序应拒绝收到的 SET 调用，并返回STATUS_INVALID_DEVICE_STATE。 在 GET 调用中，驱动程序应在“标志”字段中返回当前设置。

这是一个同步控件。 没有为此控件定义任何功能。

KSCAMERA_EXTENDEDPROP_HEADER

版本

必须为 1。

PinId

必须是与预览图钉关联的固定 ID。

大小

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

结果

指示上次 SET 操作的错误结果。 如果未执行 SET 操作，则必须为 0。

功能

必须为 0。

Flags

这是一个读/写字段。 这可以是上面定义的任意一个 KSCAMERA_EXTENDEDPROP_HISTOGRAM_XXX 标志。

KSCAMERA_EXTENDEDPROP_VALUE

未使用