扩展的相机控制

扩展控件使用 KSPROPERTY 机制向应用程序公开相机控件。

以下由 Media Foundation 定义的标准化扩展控件列表) 启用其他 Windows 相机功能 (：

• 元数据

• 焦点优先级

• 焦点状态

• 兴趣区域扩展 (ROI)

• 照片确认

• 照片序列子模式

• EXIF 和 HW JPEG 编码器

• 整数 ISO

• 高级焦点

• Flash

• Zoom

• 场景模式

某些控件作为异步控件公开给应用程序，而其他控件则作为同步控件公开。

同步控件

对于这些控件，捕获管道会发出 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);

元数据

若要检索元数据，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。在 将缓冲区向下传递到驱动程序之前，使用 KSSTREAM_HEADER_OPTIONSF_METADATA 进行 OptionFlag。

如果驱动程序不支持元数据，或者未实现KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA，KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA属性控件将失败。 在这种情况下，DevProxy 不会分配元数据缓冲区，并且从 DevProxy 传递到驱动程序的有效负载将不包含 KSSTREAM_METADATA_INFO 结构。

如果驱动程序支持元数据，而客户端不需要任何元数据，则 DevProxy 在将缓冲区发送到驱动程序时既不会分配元数据缓冲区，也不会向下传递 KSSTREAM_METADATA_INFO 。 如果应用不需要给定引脚上的元数据，此行为可以减少不必要的元数据内存分配。

以下结构描述了元数据缓冲区中相机驱动程序要填充的元数据项的布局。

• KSCAMERA_MetadataId

• KSCAMERA_METADATA_ITEMHEADER

• KSCAMERA_METADATA_PHOTOCONFIRMATION

下面的列表包含元数据项的布局。 这必须是 8 字节对齐的。

• KSCAMERA_METADATA_ITEMHEADER

• 元数据

照片确认元数据由 MetadataId_PhotoConfirmation标识。 如果存在，则表示关联的预览帧是照片确认帧。 照片确认元数据由 DevProxy 分析。

自定义元数据由从 MetadataId_Custom_Start 开始的 MetadataId 标识。 自定义元数据项可以包含元数据 blob，这些元数据可以是为预览图钉、EXIF 和/或图像固定的 OEM 元数据检测到的焦点状态和/或人脸。 自定义 Blob 的确切格式由实现驱动程序和 MFT0 的 OEM 确定。 MFT0 负责分析自定义 Blob，并将每个元数据项附加为 MFSampleExtension_CaptureMetadata属性包 下分组的属性，格式可由 MF 捕获管道和/或 WinRT 读取。

mfapi.h 中定义了以下 IMFAttributes。 这些是 MF 捕获管道和/或 WinRT 所必需的。 请注意，MFT0 不会为照片确认设置任何 IMFAttributes，因为照片确认帧不会流过 DevProxy。

特性 (GUID)	数据类型
MF_CAPTURE_METADATA_FOCUSSTATE	UINT32
MF_CAPTURE_METADATA_FACEROIS	Blob
MF_CAPTURE_METADATA_FRAME_RAWSTREAM	IUnknown

MF_CAPTURE_METADATA_FRAME_RAWSTREAM IMFAttributes 由 DevProxy 创建并附加到MFSampleExtension_CaptureMetadata，其中包含指向与原始元数据缓冲区 (KSSTREAM_METADATA_INFO关联的 IMFMediaBuffer 接口的指针。数据) 。

当 MFT0 收到 IMFSample 时，它会从 MF_CAPTURE_METADATA_FRAME_RAWSTREAM 获取原始元数据缓冲区，并分析任何其他自定义元数据项（例如焦点状态），并将其转换为上面定义的相应 IMFAttributes，并将其附加到 MFSampleExtension_CaptureMetadata 属性包。 以下 IMFAttributes 必须由 MF 管道和任何第三方提供的 MCT 传递：

名称	类型
MFSampleExtension_CaptureMetadata	IUnknown (IMFAttributes)
MFSampleExtension_EOS	UINT32 (布尔)
MFSampleExtension_PhotoThumbnail	IUnknown (IMFMediaBuffer)
MFSampleExtension_PhotoThumbnailMediaType	IUnknown (IMFMediaType)

若要访问原始元数据缓冲区，MFT0 将执行以下操作：

1. 从 IMFSample 接口调用MFSampleExtension_CaptureMetadata上的 GetUnknown，以获取属性包的 IMFAttributes 接口。

2. 从上一步获取的 IMFAttributes 接口调用 MF_CAPTURE_METADATA_FRAME_RAWSTREAM上的 GetUnknown，以获取 IMFMediaBuffer 接口。

3. 调用 Lock 获取与 IMFMediaBuffer 关联的原始元数据缓冲区。

若要将所需的 IMFAttributes 添加到 MFSampleExtension_CaptureMetadata 属性包，MFT0 将执行以下操作：

1. 从 IMFSample 接口调用MFSampleExtension_CaptureMetadata上的 GetUnknown，以获取属性包的 IMFAttributes 接口。

2. 根据上表中指定的 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_ROI_CONFIGCAPS

• KSPROPERTY_CAMERACONTROL_EXTENDED_ROI_ISPCONTROL

照片确认

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 和变体类型，并将其附加到 MFSampleExtension_CaptureMetaData 属性包，供 OEM 组件使用。 如果 HW JPEG 编码器可用，管道照片接收器组件将使用 IPropertyBag2：：Write 方法加载 HW JPEG 编码器，并将MFSampleExtension_CaptureMetaData属性包中保存的 EXIF 数据设置为 EXIF 编码器选项。

编码器选项属性包包含一组PROPBAG2结构，这些结构指定可用的编码选项属性。 设置为 HW JPEG 编码器上的 EXIF 编码器选项由编码器选项属性包中的以下属性标识：

属性名称	VARTYPE	值	适用的编解码器
SampleMetaData	VT_UNKNOWN	指向包含包含 EXIF 数据的 OEM 子属性 包MFSampleExtension_CaptureMetaData 属性包的 IMFAttributes 接口的指针。	JPEG

MFSampleExtension_CaptureMetaData属性包只能包含 MFT0 和 HW JPEG 编码器可以读取以保存 EXIF 数据的任何 OEM 定义的 EXIF 子属性。 若要将 EXIF 数据从驱动程序传递到 HW JPEG 编码器，驱动程序和 MFT0 必须执行以下操作：

1. 驱动程序在管道提供的元数据缓冲区中提供自定义 EXIF 元数据。 当示例返回至 DevProxy 时，DevProxy 会将其作为 MF_CAPTURE_METADATA_FRAME_RAWSTREAM IMFAttribute 附加到MFSampleExtension_CaptureMetadata。

2. 当 MFT0 收到 IMFSample 时，它会从 MF_CAPTURE_METADATA_FRAME_RAWSTREAM 获取原始元数据缓冲区，并分析自定义 EXIF 元数据项，并将其转换为 OEM 定义的 IMFAttribute 并将其附加到 MFSampleExtension_CaptureMetadata 属性包。

若要将 EXIF 数据从 MFT0 传递到 HW JPEG 编码器，管道照片接收器将执行以下操作：

1. 从 IMFSample 调用MFSampleExtension_CaptureMetadata上的 GetUnknown，以便在收到 IMFSample 时获取属性包的 IMFAttributes 接口。

2. 调用 IPropertyBag2：：Write 将 SampleMetadata 标识的编码器选项属性设置为 HW JPEG 编码器。 编码器选项属性包含从上一步获取的 IMFAttributes 接口。 此接口包含所有自定义子属性，包括 OEM EXIF 子属性，以及本主题前面讨论的 元数据 部分中的标准化子属性。

若要检索 EXIF 数据以供进一步处理，HW JPEG 编码器将执行以下操作：

1. 调用 IPropertyBag2：：Read 检索由 SampleMetadata 属性名称和 VT_UNKNOWN 类型标识的属性的属性值。 返回时， VARIANT.punkVal 接收 MFSampleExtension_CaptureMetadata的 IMFAttributes 接口。

2. 从上一步获取的接口调用 OEM EXIF 子属性上的 GetBlob 或 GetUnknown ，以基于 OEM EXIF 子属性的 GUID 和数据类型获取 EXIF 数据 Blob。

缩略图

无需 MFT0 即可生成相机驱动程序的任何缩略图。 相机应用应生成自己的缩略图。 缩略图可以从照片确认图像、HW JPEG 编码器或调整全尺寸图像大小生成。 这由应用开发人员决定。 为了保持 API 和应用与 Windows 8.1 应用的兼容性，相机驱动程序不得实现KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOTHUMBNAIL控件。

整数 ISO

KSPROPERTY_CAMERACONTROL_EXTENDED_ISO_ADVANCED属性 ID 是与整数 ISO DDI 关联的唯一控件。

高级焦点

KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUSMODE属性 ID 是与整数 ISO DDI 关联的唯一控件。

Flash

KSPROPERTY_CAMERACONTROL_EXTENDED_FLASHMODE属性 ID 是与闪存 DDI 关联的唯一控件。

Zoom

KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM属性 ID 是与缩放 DDI 关联的唯一控件。

场景模式

KSPROPERTY_CAMERACONTROL_EXTENDED_SCENEMODE属性 ID 是与场景模式 DDI 关联的唯一控件。