USB 视频类 1.5 规范的 Microsoft 扩展
1 概述
1.1 摘要
USB 视频类规范的 Microsoft 扩展支持新控件，以及以标准格式携带定义完善的帧元数据的功能。
1.2 体系结构决策
USB 视频类 (UVC) 帧元数据支持将提供给 ISOCH 和 BULK 终结点。 但是，对于 BULK 终结点，元数据大小将限制为 240 字节 (，因为所有视频帧数据都是在 BULK 终结点) 上的单个视频帧数据包中传输的。
UVC 元数据支持将仅适用于基于帧的有效负载。
UVC 元数据支持只能通过媒体基础 (MF) 捕获管道提供。
UVC 元数据将选择加入。 每个需要元数据支持的 IHV/OEM 都必须通过自定义 INF 文件启用此功能。
UVC 元数据仅支持系统分配的内存。 将不支持 VRAM 或 DX 图面。
2 体系结构概述
2.1 说明
2.2.1 通过 INF 发现功能
2.2.1.1 静止图像捕获 - 方法 2
某些现有 UVC 设备可能不支持第 2.4.2.4 节中所述的方法 2， (可在 USB 视频类规范网站上下载的 UVC 1.5 类 specification.pdf的静态图像捕获) 。
在 Windows 10 版本 1607 及更早版本中，捕获管道未利用方法 2，即使设备根据 UVC 1.5 规范播发了对方法 2 的支持也是如此。
在 Windows 10 版本 1703 中，利用此方法的设备必须为相机驱动程序使用自定义 INF 文件，但给定硬件需要自定义 INF 才能启用方法 2 静态图像捕获) 。
注意：相机驱动程序可以基于 Windows USBVIDEO.SYS，也可以基于自定义驱动程序二进制文件。
基于自定义 UVC 驱动程序或收件箱 UVC 驱动程序的自定义 INF 文件应包含以下 AddReg 条目：
EnableDependentStillPinCapture： REG_DWORD： 0x0 (Disabled) to 0x1 (Enabled)
如果此项设置为 Enabled (0x1) ，则捕获管道将利用方法 2 进行静态图像捕获 (假设固件还播发对 UVC 1.5 规范) 指定的方法 2 的支持。
自定义 INF 部分的示例如下所示：
[USBVideo.NT.Interfaces]
AddInterface=%KSCATEGORY_CAPTURE%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_RENDER%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_VIDEO%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_RENDER_EXT%,GLOBAL,USBVideo.Interface
AddInterface=%KSCATEGORY_VIDEO_CAMERA%,GLOBAL,USBVideo.Interface
[USBVideo.Interface]
AddReg=USBVideo.Interface.AddReg
[USBVideo.Interface.AddReg]
HKR,,CLSID,,%ProxyVCap.CLSID%
HKR,,FriendlyName,,%USBVideo.DeviceDesc%
HKR,,RTCFlags,0x00010001,0x00000010
HKR,,EnableDependentStillPinCapture,0x00010001,0x00000001
2.2.2 扩展单元控件
Microsoft 对启用新控件的 USB 视频类规范 的扩展是通过 GUID 标识的扩展单元完成的，MS_CAMERA_CONTROL_XU (称为 Microsoft-XU) 。
// {0F3F95DC-2632-4C4E-92C9-A04782F43BC8}
DEFINE_GUID(MS_CAMERA_CONTROL_XU,
0xf3f95dc, 0x2632, 0x4c4e, 0x92, 0xc9, 0xa0, 0x47, 0x82, 0xf4, 0x3b, 0xc8);
由设备固件实现的 Microsoft-XU 将容纳以下子部分中定义的新控件。 以下请求定义适用于所有这些控件，除非为该控件显式指定替代定义。 有关 D3、D4、GET_INFO等的定义，请参阅 UVC 1.5 类 specification.pdf。
GET_INFO请求应报告控件而不使用 AutoUpdate 和异步功能 (例如，D3 和 D4 位应设置为 0) 。
GET_LEN请求应报告此控件的有效负载的最大长度 (wLength) 。
GET_RES请求应报告 qwValue/dwValue 的分辨率 (步长) 。 所有其他字段应设置为 0。
GET_MIN请求应报告 qwValue/dwValue 支持的最小值。 所有其他字段应设置为 0。
GET_MAX请求应报告 qwValue/dwValue 支持的最大值。 此外，所有支持的标志应在 bmControlFlags 中设置为 1。 所有其他字段应设置为 0。
GET_DEF和GET_CUR请求应分别报告 字段 qwValue/dwValue 和 bmControlFlags 的默认设置和当前设置。 所有其他字段应设置为 0。
主机在设置所有字段后发出SET_CUR请求。
下表将 Microsoft-XU 的控件选择器映射到其各自的值以及扩展单元描述 符中 bmControls 字段的位位置：
2.2.2.1 可取消控件
可取消控件是利用自动更新功能在此处定义的。
GET_INFO请求应将此类控件报告为 Autoupdate Control (例如，D3 位应设置为 1) 但不能作为异步控制 (例如，D4 位应设置为 0) 。
对于此类控件， 可以发出SET_CUR请求以 (SET_CUR (NORMAL) 请求设置新值，其中 bmOperationFlags：D0 位设置为 0) 或取消以前的SET_CUR (NORMAL) 请求 (SET_CUR (CANCEL) 请求，其中 bmOperationFlags：D0 位设置为 1) 。 (收到请求后，设备应立即完成SET_CUR请求，即使硬件未配置或未聚合到) 请求的新设置。 对于每个SET_CUR (NORMAL) 请求，设备都会在应用新设置或SET_CUR (CANCEL) 请求到达时为此控件生成相应的控制更改中断;在此中断到达之前，SET_CUR (NORMAL) 请求将被视为正在进行。 当SET_CUR (NORMAL) 请求正在进行时，对此特定控制的其他SET_CUR (NORMAL) 请求将导致失败。 SET_CUR (CANCEL) 请求应始终成功。 如果没有任何可取消操作，则设备不会执行任何操作。
例如，如果 (应用了 SET_CUR (NORMAL) 指定的设置，则控制更改中断有效负载应将位 bmOperationFlags：D0 设置为 0，例如，如果由于SET_CUR (NORMAL) 请求后发出SET_CUR (CANCEL) ) 请求 (，则收敛) 未应用，则设置为 1。 收敛尚未) 发生。
2.2.2.2 焦点控制
此控件允许主机软件指定相机的焦点设置。 这是一个全局控件，它影响与视频控制接口关联的所有视频流接口上的所有终结点。
此控件应充当可取消的控制 (请参阅第 2.2.2.1 节，了解GET_INFO请求要求和SET_CUR请求) 的功能行为。
GET_MAX要求：此控件应在 bmControlFlags 中播发对位 D0、D1、D2、D8 和 D18 的支持。
GET_DEF要求： bmControlFlags 的默认值应为 D0，D18 设置为 1，dwValue 设置为 0。
对于GET_CUR/SET_CUR请求，以下限制适用于字段 bmControlFlags：
在 D0、D1 和 D8 位中，只能设置一个位：如果设置了 D2 位，则设置的这些参数都没有有效。
在 D16、D17、D18、D19 和 D20 中，只能设置一个位：设置的它们都没有有效。
D1 与当前 (D0、D2、D8、D16、D17、D18、D19 和 D20) 定义的所有其他位不兼容。
D2 与 D1 和 D8 不兼容。
如果未设置 D0，则 D2 与 D16、D17、D18、D19 和 D20 不兼容。
2.2.2.3 曝光控制
此控件允许主机软件指定相机的曝光设置。 这是一个全局控件，它影响与视频控制接口关联的所有视频流接口上的所有终结点。
GET_INFO请求应将此控件报告为异步控件 (例如，D4 位应设置为 1) 但不能作为 AutoUpdate 控件 (例如，D3 位应设置为 0) 。
GET_MAX要求：此控件应在 bmControlFlags 中播发对位 D0、D1 和 D2 的支持。
GET_DEF要求： bmControlFlags 的默认值应设置为 D0 设置为 1，qwValue 设置为 0。
对于GET_CUR/SET_CUR请求，以下限制适用于字段 bmControlFlags：
在 D0、D1 和 D2 位中，至少应设置一个位。
D1 与 D0 和 D2 不兼容。
2.2.2.4 EV 补偿控制
此控件允许主机软件指定相机的 EV 补偿设置。 这是一个全局控件，它影响与视频控制接口关联的所有视频流接口上的所有终结点。
GET_INFO请求应将此控件报告为异步控件 (例如，D4 位应设置为 1) 但不能作为 AutoUpdate 控件 (例如，D3 位应设置为 0) 。
GET_RES请求应通过在 bmControlFlags 中设置相应的位来报告所有受支持的分辨率 (步长) 。 所有其他字段应设置为 0。
GET_MIN和GET_MAX请求应报告 dwValue 支持的最小值和最大值。 指示步长为 1) 的位 D4 (应是 bmControlFlags 中设置的唯一位。 所有其他字段应设置为 0。
GET_DEF、GET_CUR、SET_CUR请求应遵循第 2.2.2.1 节中的定义，但在字段 bmControlFlags 的 D0、D1、D2、D3 和 D4 位之间应设置一个且只有一个位。 此外，GET_DEF请求应将 dwValue 设置为 0。
2.2.2.5 白平衡控制
此控件允许主机软件指定相机的白平衡设置。 这是一个全局控件，它影响与视频控制接口关联的所有视频流接口上的所有终结点。
GET_INFO请求应将此控件报告为异步控件 (例如，D4 位应设置为 1) 但不能作为 AutoUpdate 控件 (例如，D3 位应设置为 0) 。
GET_RES，GET_MIN，GET_MAX请求应遵循第 2.2.2.1 节中的定义，但 dwValueFormat 应设置为 1。
GET_MAX要求：此控件应在 bmControlFlags 中播发对位 D0、D1 和 D2 的支持。
GET_DEF要求： bmControlFlags 的默认值应设置为 D0 设置为 1，dwValueFormat 以及 dwValue 设置为 0。
对于GET_CUR/SET_CUR请求，以下限制适用于字段 bmControlFlags：
在 D0、D1 和 D2 位中，至少应设置一个位。
D1 与 D0 和 D2 不兼容。
2.2.2.6 人脸身份验证控制
此控件允许主机软件指定相机是否支持用于人脸身份验证的流模式。 支持此控件意味着相机能够进行人脸身份验证。 否则将不支持此控件。
此控件仅适用于可生成 Infra-Red (IR) 数据的相机，并且仅适用于指定的流式处理接口 (该接口是与视频控制接口) 关联的所有视频流接口的子集。
GET_RES和GET_MIN请求应报告字段 bNumEntries 设置为 0，因此没有其他字段。
对于GET_MAX请求， bmControlFlags 字段上的位设置为 1 表示该流式处理接口支持相应的模式。 GET_MAX请求输出应列出所有且仅支持 D1 或 D2 (的流式处理接口，例如，如果流式处理接口支持 D1 或 D2，则会列出;否则，它不会列出) 。 此外，不应播发流式处理接口以同时支持 D1 和 D2。 如果流式处理接口还旨在以常规用途 (（例如，在人脸身份验证) 目的之外）使用，则除 D1/D2) 外，该流式处理接口 (的 D0 应设置为 1。
对于GET_DEF/GET_CUR/SET_CUR请求，bmControlFlags 字段中的位设置为 1 表示为该流式处理接口选择了相应的模式。 在这些请求中，应为特定的流式处理接口设置 D0、D1 & D2) 中的一个位 (。 对于返回默认选择 (实现特定) 的GET_DEF请求，如果流式处理接口还旨在以常规用途的方式使用 (，例如，除了人脸身份验证) 目的之外，则在该流式处理接口上，D0 应默认设置为 1;否则，D1 或 D2 (但不同时) 默认设置为 1。 GET_DEF/GET_CUR请求输出应包含有关GET_MAX请求输出中列出的所有流式处理接口的信息，但是，SET_CUR请求只能包含GET_MAX请求输出中列出的流式处理接口的子集。
示例：
假设相机有四个视频流接口，其数字分别为0x03、0x05、0x08和0x0b，其中视频流接口0x05生成 RGB 数据，其余三个视频流接口生成 IR 数据。 在生成 IR 数据的流式处理接口中，假设流式处理接口0x03和0x0b都能够 D1，但流式处理接口0x03也能够 D0。 在此示例中，人脸身份验证控件仅适用于编号0x03和0x0b的流式处理接口，因此只有这些接口将显示在请求中。
GET_MAX请求的输出应如下所示：
GET_DEF请求的输出应如下所示：
SET_CUR请求将流式处理接口上的设置0x03更改为 D1，如下所示：
上述SET_CUR请求之后GET_CUR请求的输出应如下所示：
2.2.2.7 相机外在控制
此控件允许主机软件获取与视频控制接口关联的视频流接口上的终结点的相机外部数据。 这样为每个终结点获取的数据将在属性存储上显示为属性MFStreamExtension_CameraExtrinsics，用于使用 IMFDeviceTransform：：GetOutputStreamAttributes 调用) 获取的相应流 (。
GET_RES、GET_MIN、GET_MAX、GET_CUR请求应报告字段 bNumEntries 设置为 0，因此没有其他字段。
GET_DEF请求应列出具有可用外在信息的所有终结点。
示例：
假设相机有三个视频流接口，其数字分别为0x03、0x05和0x08，其中视频流接口0x05除了支持所有视频流接口支持的视频捕获外，还支持使用方法 2 捕获静态图像。 在这些流式处理接口中，假设流式处理接口0x05,0x08有可用的外在信息，而流式处理接口0x03没有可用的外在信息。
在此示例中，GET_DEF请求的输出应如下所示：
2.2.2.8 相机内部控件
此控件允许主机软件获取与视频控制接口关联的视频流式处理接口上的终结点的相机内部数据。 这样为每个终结点获取的数据将在属性存储中显示为使用 IMFDeviceTransform：：GetOutputStreamAttributes 调用) 获取的相应流 (的属性MFStreamExtension_PinholeCameraIntrinsics。
GET_RES、GET_MIN、GET_MAX、GET_CUR请求应报告字段 bNumEntries 设置为 0，因此没有其他字段。
GET_DEF请求应列出具有可用内部函数信息的所有终结点。
示例：
假设相机有三个视频流接口，其数字分别为0x03、0x05和0x08，其中视频流接口0x05除了支持所有视频流接口支持的视频捕获外，还支持使用方法 2 捕获静态图像。 在这些流式处理接口中，假设流式处理接口0x05和0x08具有可用的内部函数信息，而流式处理接口0x03没有可用的内部函数信息。
在此示例中，GET_DEF请求的输出应如下所示：
2.2.2.9 元数据控制
此控件允许主机软件查询和控制相机生成的元数据。 这是一个全局控件，会影响与视频控制接口关联的所有视频流式处理接口上的所有终结点。
此控件由相机驱动程序映射到 KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA 。
如果固件支持SET_CUR请求，则以下情况适用：
- GET_MIN，GET_DEF请求应报告字段 dwValue 设置为 0。
- GET_RES请求应将字段 dwValue 报告为GET_MAX请求报告的相同值。
- 当收到 dwValue 设置为 0 的SET_CUR请求时，相机不应生成任何元数据。 如果收到SET_CUR请求，并将 dwValue 设置为与GET_MAX请求报告的值相同，则相机可以生成元数据，并且此类元数据的大小不能超过任何帧的 dwValue 。
如果固件不支持SET_CUR请求，则适用以下内容：
- GET_MIN，GET_DEF请求应报告字段 dwValue 与GET_MAX请求报告的值相同。
- GET_RES请求应报告字段 dwValue 设置为 0。
- 相机可以生成元数据，并且此类元数据的总大小不能超过 dwValue （如GET_MAX请求报告的那样），对于任何帧，其大小小于 UsbVideoHeader 元数据有效负载大小的 1024 字节。
- UsbVideoHeader 元数据有效负载的大小为 (KSCAMERA_METADATA_ITEMHEADER) + 大小为 (KSTREAM_UVC_METADATA) 或 24 个字节。
生成的元数据应符合第 2.2.3 节中所述的 Microsoft 标准格式元数据。
2.2.2.10 IR 火炬控制
此控件为 IR LED 硬件提供了一种灵活的方法，用于报告其可控制的程度，并提供对其进行控制的能力。 这是一个全局控件，它通过调整连接到相机的 IR 灯的电源，影响与视频控制接口关联的所有视频流接口上的所有终结点。
此控件由相机驱动程序映射到 KSPROPERTY_CAMERACONTROL_EXTENDED_IRTORCHMODE 。
适用以下说明：
- GET_LEN请求应报告值为 8。
- GET_INFO请求应报告 3. 此值指示支持GET_CUR和SET_CUR的同步控件。
- GET_MIN请求应报告字段 dwMode 设置为 0，dwValue 设置为指示最小功率的值。 功率级别为 0 可能表示 OFF，但最低工作功率级别不必为 0。
- GET_RES请求应报告字段 dwMode 设置为 0，dwValue 设置为小于或等于GET_MAX (dwValue) – GET_MIN (dwValue) ，以便GET_MAX (dwValue) – GET_MIN (dwValue) 被该值均匀地除以。 dwValue 不能为零 (0) 。
- GET_MAX请求应报告字段 dwMode 集，其中设置了 D[0-2] 位，以标识此控件的功能。 dwMode 必须设置位 D0，表示支持 OFF，并且它必须至少设置一个其他位，支持活动状态。 dwValue 必须设置为指示正常功率的值。
- GET_DEF请求应报告字段 dwMode 设置为系统在流式处理开始前应处于的默认模式。 dwMode 必须设置为 2 (ON) 或 4 (交替) 。 dwValue 应设置为通常用于 FaceAuth 控件的功率级别。 dwValue 由制造商定义。
- GET_CUR请求应报告字段 dwMode 设置为当前操作模式， 将 dwValue 设置为当前照明。
- 收到SET_CUR请求时，IR Torch 将使用请求的操作模式将照明设置为按比例的强度。
IR 火炬必须发出每个帧的 MF_CAPTURE_METADATA_FRAME_ILLUMINATION 属性。 它可以通过设备 MFT 或相机的元数据有效负载中包含 MetadataId_FrameIllumination 属性来提供此功能。 请参阅 2.2.3.4.4 节。
此元数据的唯一用途是指示帧是否亮起。 这是 KSPROPERTY_CAMERACONTROL_EXTENDED_FACEAUTH_MODE DDI 和第 2.2.2.6 节中定义的 MSXU_FACE_AUTHENTICATION_CONTROL 所需的相同元数据。
2.2.2.11 数字窗口控件
数字窗口指定相机流式传输时相机的视野和缩放。 此控件是“平移”、“倾斜”和“缩放”的可能替代项。 此控件仅在相机主动流式传输时适用。
此控件可用于所有类型的相机，并且与正在流式传输的媒体类型无关。
此控件允许主机软件查询和控制与相机关联的数字窗口。
这是一个全局控件，会影响与视频控制接口关联的所有视频流式处理接口上的所有终结点。 它调整 ISP 使用的像素数据源。 这包括方法 2 和方法 3 仍捕获引脚。
此控件映射到收件箱相机驱动程序 KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW 。
适用以下说明：
GET_LEN请求应报告值为 16。
GET_INFO请求应报告 3. 此值指示支持GET_CUR和SET_CUR的同步控件。
GET_MIN请求应报告字段 dwMode 设置为 0，OriginX 和 OriginY 设置为 0.0，WindowSize 设置为 1.0。 此请求当前未使用。
GET_RES请求应报告字段 dwMode 设置为 0，OriginX 和 OriginY 设置为 0.0，WindowSize 设置为 1.0。 此请求当前未使用。
GET_MAX请求应报告具有位 D0 设置的 dwMode 字段，以标识此控件的功能。 值为 0 表示仅支持手动模式。 值为 1 表示支持自动人脸取景模式。 这些字段的其余部分未使用，但是，我们建议将 OriginX 和 OriginY 设置为 0.0，WindowSize 设置为 1.0。
GET_DEF请求应报告字段 dwMode 设置为 0，OriginX 和 OriginY 设置为 0.0，WindowSize 设置为 1.0。 这始终是默认窗口。
GET_CUR请求应报告字段 dwMode 设置为当前操作模式， OriginX、 OriginY 和 WindowSize 描述当前数字窗口。
收到SET_CUR请求时，相机将调整其视场以匹配所选操作模式和数字窗口。
如果选择自动人脸取景模式，相机将选择一个窗口，该窗口将完全包含场景中的主宰人脸，并且忽略传入的 OriginX、 OriginY 和 WindowSize 。 如果未找到人脸，将使用默认窗口。
对数字窗口的任何更改都必须反映在每个样本的元数据有效负载中。
对数字窗口的更改不需要立即生效，但控件应立即响应。 对数字窗口的更改必须在其生效后立即报告在帧的元数据有效负载中。
2.2.2.12 数字窗口配置控制
数字窗口配置上限控件指定给定所有可用分辨率的相机缩放限制。 分辨率与媒体类型无关，因此广告相同显示分辨率的两种媒体类型合并为一个功能。
由于控制终结点的大小限制，此控件最多可以描述 1820 个唯一分辨率。
如果数字窗口控件也存在，则此控件必须始终可用于报告该控件的功能。
此控件映射到收件箱相机驱动程序 KSPROPERTY_CAMERACONTROL_EXTENDED_DIGITALWINDOW_CONFIGCAPS 。
适用以下说明：
GET_LEN请求应报告有效负载的整个大小。 有效负载大小必须是 36 的倍数，因为每个分辨率定义长度为 36 字节。
GET_INFO请求应报告 1. 此值指示仅支持GET_CUR的同步控件。
GET_CUR请求应报告一系列功能。 功能结构的字段在上面定义。
GET_MIN、GET_MAX、GET_RES和GET_DEF请求未使用，但应返回与GET_CUR相同的值。
不支持SET_CUR请求。
2.2.2.13 视频 HDR 控制
此控件允许主机软件指定相机是否支持视频 HDR。 支持此控件意味着相机能够尽最大努力执行视频 HDR。 如果相机不支持视频 HDR，则不会实现此控件。
此控件由相机驱动程序映射到 KSPROPERTY_CAMERACONTROL_EXTENDED_VIDEOHDR 。
适用以下说明：
GET_LEN请求应报告有效负载的整个大小。 例如， (4 个字节) 。
GET_INFO请求应报告值 3。 此值指示支持GET_CUR的同步控件，SET_CUR。
GET_CUR请求应报告字段 dwMode 设置为当前操作模式。
GET_DEF应将 dwMode 设置为 OFF (0) 。
GET_MAX请求应播发对可用操作模式的支持：[1 (ON/OFF) ,3 (ON/OFF/Auto) ]。 此控件必须支持 ON (1) 。
GET_MIN和GET_RES请求应报告 0。
SET_CUR请求应将模式设置为 OFF (0) 、ON (1) 或 AUTO (2) 。
2.2.3 元数据
标准格式帧元数据设计基于Windows 10的 UVC 自定义元数据设计。 在 Windows 10 中，UVC 支持使用相机驱动程序的自定义 INF (注意：相机驱动程序可以基于 Windows USBVIDEO.SYS，但给定硬件需要自定义 INF 才能使元数据通过) 。 如果 MetadataBufferSizeInKB<PinIndex> 注册表项存在且非零，则支持该引脚的自定义元数据，值指示用于元数据的缓冲区大小。 字段 <PinIndex> 指示视频固定索引的从 0 开始的索引。
在 Windows 10 版本 1703 中，相机驱动程序可以通过包含以下 AddReg 条目来发出对 Microsoft 标准格式元数据的支持信号：
StandardFormatMetadata<PinIndex>：REG_DWORD：0x0 (支持) 0x1 (支持的)
此注册表项将由 DevProxy 读取，并通过在“标志”字段中为KSSTREAM_METADATA_INFO结构设置标志KSSTREAM_METADATA_INFO_FLAG_STANDARDFORMAT，通知 UVC 驱动程序元数据采用标准格式。
2.2.3.1 Microsoft 标准格式元数据
Microsoft 标准格式元数据是以下结构的一个或多个实例：
typedef struct tagKSCAMERA_METADATA_ITEMHEADER {
ULONG MetadataId;
ULONG Size; // Size of this header + metadata payload following
} KSCAMERA_METADATA_ITEMHEADER, *PKSCAMERA_METADATA_ITEMHEADER;
MetadataId 字段由以下枚举定义的标识符填充，该定义包含明确定义的标识符以及自定义标识符 (标识符 >= MetadataId_Custom_Start) 。
typedef enum {
MetadataId_Standard_Start = 1,
MetadataId_PhotoConfirmation = MetadataId_Standard_Start,
MetadataId_UsbVideoHeader,
MetadataId_CaptureStats,
MetadataId_CameraExtrinsics,
MetadataId_CameraIntrinsics,
MetadataId_FrameIllumination,
MetadataId_Standard_End = MetadataId_FrameIllumination,
MetadataId_Custom_Start = 0x80000000,
} KSCAMERA_MetadataId;
“大小”字段设置为 sizeof (KSCAMERA_METADATA_ITEMHEADER) + sizeof (元数据有效负载) 。
2.2.3.2 来自 USB 视频帧数据包的固件生成的标准格式元数据
在通过 UVC 传输基于帧的视频期间，视频帧将数据包化为一系列数据包，每个数据包前面有一个 UVC 有效负载标头。 每个 UVC 有效负载标头由基于 USB 视频类驱动程序帧的有效负载规范定义：
有效负载标头
下面是基于帧的格式的有效负载标头格式的说明。
HLE (标头长度) 字段
标头长度字段指定标头的长度（以字节为单位）。
位字段标头字段
FID：帧标识符
- 此位在每个帧开始边界处切换，并在帧的其余部分保持不变。
EOF：帧结束
- 此位指示视频帧的末尾，并在属于帧的最后一个视频示例中设置。 使用此位是一种优化，以减少帧传输完成时的延迟，并且是可选的。
PTS：演示文稿时间戳
- 设置时，此位指示存在 PTS 字段。
SCR：源时钟参考
- 设置时，此位指示存在 SCR 字段。
RES：保留。
- 设置为 0。
STI：静止图像
- 设置后，此位将视频示例标识为属于静止图像。
ERR：错误位
- 设置时，此位表示设备流式处理出错。
EOH：标头末尾
- 设置时，此位指示 BFH 字段的末尾。
PTS：演示文稿时间戳，大小：4 字节，值：数字
- 在 BFH[0] 字段中设置 PTS 位时，会出现 PTS 字段。 请参阅视频 设备的 USB 设备类定义 规范中的第 2.4.3.3 节“视频和静止图像有效负载标头”。
SCR：源时钟引用，大小：6 字节，值：数字
- 在 BFH[0] 字段中设置 SCR 位时，存在 SCR 字段。 请参阅视频设备的 USB 设备类定义规范中的第 2.4.3.3 节视频和静态图像有效负载标头。
现有 UVC 驱动程序中的 HLE 字段固定为 2 个字节 (不存在 PTS/SCR) ，或 (PTS/SCR 存在的) 最多 12 个字节。 但是，HLE 字段是字节大小的字段，最多可以指定 255 字节的标头数据。 如果同时存在 PTS/SCR，并且 HLE 大于 12 个字节，则当设置 INF 条目 StandardFormatMetadata<PinIndex> 时，将选取有效负载标头的前 12 个字节之后的任何其他数据作为特定于视频帧的标准元数据。
(固件) 为帧生成的标准格式元数据是通过连接表示该帧的视频帧数据包中找到的部分 Blob 来获取的。
2.2.3.3 提供给用户模式组件的元数据缓冲区
提供给用户模式组件的元数据缓冲区将具有 UVC 驱动程序 (生成的 UVC 时间戳的元数据项) 后跟固件生成的元数据项，其布局如下：
2.2.3.4 标准元数据标识符的元数据格式
固件可以选择是否生成与标识符对应的元数据。 如果固件选择生成与标识符对应的元数据，则该标识符的元数据应存在于固件发出的所有帧上。
2.2.3.4.1 MetadataId_CaptureStats
此标识符的元数据格式由以下结构定义：
typedef struct tagKSCAMERA_METADATA_CAPTURESTATS {
KSCAMERA_METADATA_ITEMHEADER Header;
ULONG Flags;
ULONG Reserved;
ULONGLONG ExposureTime;
ULONGLONG ExposureCompensationFlags;
LONG ExposureCompensationValue;
ULONG IsoSpeed;
ULONG FocusState;
ULONG LensPosition; // a.k.a Focus
ULONG WhiteBalance;
ULONG Flash;
ULONG FlashPower;
ULONG ZoomFactor;
ULONGLONG SceneMode;
ULONGLONG SensorFramerate;
} KSCAMERA_METADATA_CAPTURESTATS, *PKSCAMERA_METADATA_CAPTURESTATS;
Flags 字段指示结构中哪些后续字段已填充并具有有效数据。 标志字段不会因帧而异。 目前，定义了以下标志：
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_EXPOSURETIME 0x00000001
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_EXPOSURECOMPENSATION 0x00000002
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_ISOSPEED 0x00000004
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FOCUSSTATE 0x00000008
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_LENSPOSITION 0x00000010
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_WHITEBALANCE 0x00000020
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FLASH 0x00000040
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_FLASHPOWER 0x00000080
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_ZOOMFACTOR 0x00000100
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_SCENEMODE 0x00000200
#define KSCAMERA_METADATA_CAPTURESTATS_FLAG_SENSORFRAMERATE 0x00000400
“保留”字段是为将来保留的，应设置为 0。
“曝光时间”字段包含捕获帧时应用于传感器的曝光时间（以 100ns 为单位）。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_EXPOSURE_TIME。
ExposureCompensationFlags 字段包含 EV 补偿步骤 (应设置KSCAMERA_EXTENDEDPROP_EVCOMP_XXX步骤标志之一，) 用于传达 EV 补偿值。 ExposureCompensationValue 字段包含 EV 补偿值（以捕获帧时应用于传感器的步骤的单位）。 这些将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION。
IsoSpeed 字段包含捕获帧时应用于传感器的 ISO 速度值。 这是无单位的。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_ISO_SPEED。
FocusState 字段包含当前焦点状态，该状态可以采用枚举KSCAMERA_EXTENDEDPROP_FOCUSSTATE中定义的值之一。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_FOCUSSTATE。
LensPosition 字段包含捕获帧时的逻辑镜头位置，这是无单位的。 此值与可从 GET 调用中的KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS查询的值相同。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_LENS_POSITION。
WhiteBalance 字段包含捕获帧时应用于传感器的白平衡，该值以 Kelvin 为单位。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_WHITEBALANCE。
Flash 字段包含一个布尔值，其中 1 表示在捕获帧时闪烁，0 表示闪烁关闭。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_FLASH。
FlashPower 字段包含应用于捕获的帧的闪存功率，该帧是 [0， 100] 范围内的值。 如果驱动程序不支持闪存的可调电源，则应省略此字段。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_FLASH_POWER。
ZoomFactor 字段包含应用于捕获的帧的 Q16 格式的缩放值。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_ZOOMFACTOR。
SceneMode 字段包含应用于捕获的帧的场景模式，该帧是一个 64 位KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX标志。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_SCENE_MODE。
捕获帧时 ，SensorFramerate 字段包含测量的传感器读出速率（以赫为单位），该速率由上 32 位的分子值和低 32 位的分母值组成。 这将在相应的 MF 示例中显示为属性MF_CAPTURE_METADATA_SENSORFRAMERATE。
2.2.3.4.2 MetadataId_CameraExtrinsics
此标识符的元数据格式涉及标准KSCAMERA_METADATA_ITEMHEADER后跟字节数组有效负载。 有效负载应与 MFCameraExtrinsics 结构对齐，后跟零个或多个 MFCameraExtrinsic_CalibratedTransform 结构。 有效负载必须是 8 字节对齐的，所有未使用的字节应出现在有效负载的末尾，并设置为 0。
2.2.3.4.3 MetadataId_CameraIntrinsics
此标识符的元数据格式涉及标准KSCAMERA_METADATA_ITEMHEADER后跟字节数组有效负载。 有效负载应与 MFPinholeCameraIntrinsics 结构对齐。 有效负载必须是 8 字节对齐的，所有未使用的字节应出现在有效负载的末尾，并设置为 0。
2.2.3.4.4 MetadataId_FrameIllumination
此标识符的元数据格式由以下结构定义：
typedef struct tagKSCAMERA_METADATA_FRAMEILLUMINATION {
KSCAMERA_METADATA_ITEMHEADER Header;
ULONG Flags;
ULONG Reserved;
} KSCAMERA_METADATA_FRAMEILLUMINATION, *PKSCAMERA_METADATA_FRAMEILLUMINATION;
“标志”字段指示有关捕获的帧的信息。 目前，定义了以下标志：
#define KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON 0x00000001
如果在照明打开时捕获了帧，则应设置标志KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON。 否则，不应设置此标志。
保留字段保留供将来使用，应设置为 0。
示例：
例如，指示照明已打开的KSCAMERA_METADATA_FRAMEILLUMINATION结构如下所示：
KSCAMERA_METADATA_FRAMEILLUMINATION.Header.MetadataId = MetadataId_FrameIllumination;
KSCAMERA_METADATA_FRAMEILLUMINATION.Header.Size = 16; // 4 ULONG variables in total inside the structure
KSCAMERA_METADATA_FRAMEILLUMINATION.Flags = KSCAMERA_METADATA_FRAMEILLUMINATION_FLAG_ON;
KSCAMERA_METADATA_FRAMEILLUMINATION.Reserved = 0;
2.2.3.4.5 MetadataId_USBVideoHeader
此标识符的元数据格式由通用KSCAMERA_METADATA_ITEMHEADER后跟KSSTREAM_UVC_METADATA结构定义：
typedef struct
{
ULONG PresentationTimeStamp;
ULONG SourceClockReference;
union
{
struct
{
USHORT Counter : 11;
USHORT Reserved : 5;
};
USHORT SCRToken;
};
USHORT Reserved0;
ULONG Reserved1;
} KSSTREAM_UVC_METADATATYPE_TIMESTAMP, *PKSSTREAM_UVC_METADATATYPE_TIMESTAMP;
typedef struct {
KSSTREAM_UVC_METADATATYPE_TIMESTAMP StartOfFrameTimestamp;
KSSTREAM_UVC_METADATATYPE_TIMESTAMP EndOfFrameTimestamp;
} KSSTREAM_UVC_METADATA, *PKSSTREAM_UVC_METADATA;
StartOfFrameTimestamp 和 EndOfFrameTimestamp 字段是相机为构造此帧而发出的第一个和最后一个 UVC 有效负载中的 UVC 标头中包含的时间戳。
此有效负载不应由设备发送。
此元数据有效负载是唯一的，因为它是 USB 视频类驱动程序直接从从符合 UVC 的有效负载标头获取的信息生成的唯一元数据有效负载。
此有效负载位于每个帧的元数据缓冲区前面。
如果设备支持标准化元数据，则必须将存储此有效负载所需的空间包含在其缓冲区要求中，如第 2.2.2.2.9 节中定义的元数据控件所报告的那样。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈