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 设备可能不支持在 USB 视频类规范网站下载的 UVC 1.5 类 specification.pdf 的第 2.4.2.4 节（静态图像捕获）中所述的方法 2。

在 Windows 10 版本 1607 及更早版本中，捕获管道不使用方法 2，即使设备根据 UVC 1.5 规范播发了对它的支持。

在 Windows 10 版本 1703 中，使用此方法的设备必须使用相机驱动程序的自定义 INF 文件，但给定硬件需要自定义 INF 才能启用方法 2 静态图像捕获。）

注意：相机驱动程序可以基于 Windows USBVIDEO.SYS，也可以基于自定义驱动程序二进制文件。

基于自定义 UVC 驱动程序或收件箱 UVC 驱动程序的自定义 INF 文件应包含以下 AddReg 条目：

EnableDependentStillPinCapture：REG_DWORD： 0x0 (Disabled) 到 0x1 (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 通过 GUID MS_CAMERA_CONTROL_XU（称为 Microsoft-XU）标识的扩展单元对 USB 视频类规范进行扩展，以启用新的控件。

// {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 请求应报告没有自动更新和异步功能的控件（例如，D3 和 D4 位应设置为 0）。

GET_LEN 请求应报告此控件的有效负载的最大长度 (wLength)。

GET_RES 请求应报告 qwValue/dwValue 的分辨率 (step-size)。 所有其他字段应设置为 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 字段的位位置：

控件选择器	值	位位置 （bmControls 字段）
MSXU_CONTROL_UNDEFINED	0x00	NA
MSXU_CONTROL_FOCUS	0x01	D0
MSXU_CONTROL_EXPOSURE	0x02	D1
MSXU_CONTROL_EVCOMPENSATION	0x03	D2
MSXU_CONTROL_WHITEBALANCE	0x04	D3
预留供以后使用	0x05	D4
MSXU_CONTROL_FACE_AUTHENTICATION	0x06	D5
MSXU_CONTROL_CAMERA_EXTRINSICS	0x07	D6
MSXU_CONTROL_CAMERA_INTRINSICS	0x08	D7
MSXU_CONTROL_METADATA	0x09	D8
MSXU_CONTROL_IR_TORCH	0x0A	D9
MSXU_CONTROL_DIGITALWINDOW	0x0B	D10
MSXU_CONTROL_DIGITALWINDOW_CONFIG	0X0C	D11
MSXU_CONTROL_VIDEO_HDR	0X0D	D12
MSXU_CONTROL_FRAMERATE_THROTTLE	0x0E	D13
MSXU_CONTROL_FIELDOFVIEW2_CONFIG	0x0F	D14
MSXU_CONTROL_FIELDOFVIEW2	0x10	D15

2.2.2.1 可取消控件

此处使用自动更新功能定义了一个可取消控件。

GET_INFO 请求应将此类控制报告为自动更新控制（例如，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) 请求应始终成功。 如果没有任何内容要取消，则设备不执行任何操作。

如果应用了标准版T_CUR（NORMAL）指定的设置（例如，发生收敛），并且由于标准版T_CUR（NORMAL）请求之后发生的标准版T_CUR（CANCEL）请求（例如，收敛尚未发生），则控制更改中断有效负载应将位 bmOperationFlags：D0 设置为 0。

2.2.2.2 对焦控件

此控件允许主机软件指定相机的对焦设置。 这是一个全局控件，它影响与视频控制接口关联的所有视频流式处理接口上的所有端点。

此控件应充当可取消控件（请参阅第 2.2.2.1 节，了解 SET_CUR 请求的 GET_INFO 请求要求和功能行为）。

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），而不是自动更新控制（例如，D3 位应设置为 0）。

GET_MAX 要求：此控件应在 bmControlFlags 中播发对位 D0、D1、D2 的支持。

GET_DEF 要求：bmControlFlags 的默认值应为 D0，D18 设置为 1，qwValue 设置为 0。

对于 GET_CUR/SET_CUR 请求，以下限制适用于字段 bmControlFlags：

• 在 D0、D1 和 D2 位中，应至少设置一位。
• D1 与 D0 和 D2 不兼容。

2.2.2.4 EV 补偿控制

此控件允许主机软件指定相机的 EV 补偿设置。 这是一个全局控件，它影响与视频控制接口关联的所有视频流式处理接口上的所有端点。

GET_INFO 请求应将此控件报告为异步控制（例如，D4 位应设置为 1），而不是自动更新控制（例如，D3 位应设置为 0）。

GET_RES 请求应通过设置 bmControlFlags 中的相应位来报告所有支持的分辨率 (step-size)。 所有其他字段应设置为 0。

GET_MIN 和 GET_MAX 请求应报告 dwValue 支持的最小值和最大值。 位 D4（指示步骤大小为 1）应为 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），而不是自动更新控制（例如，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 人脸身份验证控制

此控件允许主机软件指定相机是否支持用于人脸身份验证的流式处理模式。 支持此控件意味着相机能够进行人脸身份验证。 否则，不应支持此控件。

此控件仅适用于能够生成红外 (IR) 数据的相机，并且仅适用于指定的流式处理接口（这是与视频控制接口关联的所有视频流式处理接口的子集）。

GET_RES 和 GET_MIN 请求应报告字段 bNumEntries 设置为 0，因此没有其他字段。

对于 GET_MAX 请求，bmControlFlags 字段上的位设置为 1，表示该流式处理接口支持相应的模式。 GET_MAX 请求输出应列出支持 D1 或 D2 的所有流式处理接口（例如，如果流式处理接口能够 D1 或 D2，则会列出；否则不会列出）。 此外，任何流媒体接口都不得播发为同时支持 D1 和 D2。 如果流式处理接口还用于常规用途（例如，在人脸身份验证以外的目的），则该流媒体接口的 D0（除 D1/D2 外）应设为 1。

对于 GET_DEF / GET_CUR / SET_CUR 请求，bmControlFlags 字段上的位设置为 1 表示为该流式处理接口选择了相应的模式。 在这些请求中，应为特定的流式处理接口设置一位且仅一位（在 D0、D1 & D2 中）。 对于返回默认选择（特定于实现）的 GET_DEF 请求，如果流式处理接口也用于常规用途（例如，人脸身份验证之外的目的），则默认情况下，D0 应设置为 1；否则，默认情况下，D1 或 D2 应设为 1（但不能同时设置为 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 请求的输出应如下所示：

将流式处理接口上的设置 0x03 更改为 D1 的 SET_CUR 请求如下所示：

上述SET_CUR 请求后 GET_CUR 请求的输出应如下所示：

2.2.2.7 相机外部控制

此控件允许主机软件获取与视频控制接口关联的视频流接口上的端点的相机外向数据。 由此获得的每个端点的数据会显示为相应数据流（使用 IMFDeviceTransform::GetOutputStreamAttributes 调用获得）属性存储中的 MFStreamExtension_CameraExtrinsics 属性。

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 元数据有效负载是 sizeof (KSCAMERA_METADATA_ITEMHEADER) + sizeof(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 Torch 必须为每个帧发出 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 请求应报告字段 dwMode 集，其中设置了位 D0 来标识此控件的功能。 值为 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.2.14 帧速率节流控件

此控件允许主机软件指定相机是否支持帧速率节流。

此控件仅在相机主动流式传输时适用。 主动流式传输意味着预览或记录引脚必须处于 KSSTATE_RUN 状态，并且随时能够传送帧。 如果集中流未处于活动状态，此控件应返回 STATUS_INVALID_DEVICE_STATE。

即使这是筛选器范围控件，帧速率控件也不应影响照片引脚或无 RGB 流（如 IR/深度）。 此外，当帧速率节流生效时，还应相应地调整样本持续时间。

此控件由相机驱动程序映射到 KSPROPERTY_CAMERACONTROL_EXTENDED_FRAMERATE_THROTTLE 。

控件选择器	MSXU_CONTROL_FRAMERATE_THROTTLE
强制请求	GET_INFO、GET_LEN、GET_RES、GET_MIN、GET_MAX、GET_DEF、GET_CUR、SET_CUR
可选请求
wLength	20

Offset	字段	大小	值	说明
0	dwMode	4	标记	D0：0 (OFF) 或 1 (ON) D1-D31：保留并设置为 0
4	scaleFactorPercentage	4	Number	此值应位于 Min 和 Max 的范围内，并应将其设置为 Step 值的倍数。 例如：如果 Min = 5，Max = 100，Step = 5，且如果应用程序决定将帧速率降低到原始值的 80%，则应将此成员值设置为 80。 通过适当设置此值，应用可以确保新帧速率永远不会超过原始值，也不会归零，但原始帧速率是可能的。
8	min	4	Number	最小值应等于租约一步大小，或者它应是步骤大小的倍数（例如：步骤 1、步骤 2 等）。 最小值不能设置为 0。
12	max	4	Number	最大值必须设置为 100，这意味着帧速率没有变化。
16	step	4	Number	步骤应是 Max 的严格因素，例如 {Max % Step == 0}。 示例：1、2、4、5 等。

以下内容适用：

• GET_LEN 请求应报告负载的整个大小（例如 20 个字节）。 

• GET_INFO 请求应报告值 3。 此值指示支持 GET_CUR 和 SET_CUR 的同步控件。 

• GET_CUR 请求应报告字段 dwMode 设置为当前操作模式，scaleFactorPercentage 设置为当前 scaleFactor 值。 最小值、最大值和步骤应按上表所述报告值。

• GET_DEF 应将 dwMode 设置为 OFF (0)，scaleFactorPercentage=100，最小值设置为默认值，最大值设置为 100，步骤设置为默认步骤值。 最小值和步骤的值应由制造商定义，但应遵循上表中提及的准则。

• GET_ MAX 请求应播发对可用操作模式的支持，并将报告值 1 [ ON |OFF ]。 此控件必须同时支持 ON 和 OFF。 最小、最大、步骤和 scaleFactorPercentage 可以设置为默认值。

• GET_MIN 和 GET_RES 请求应报告 0。 

• SET_CUR 请求应将模式设置为 OFF (0) 或 ON (1)。 如果 dwMode 设置为 ON，则 scaleFactorPercentage 应生效。 对于 OFF 和 ON 的情况，scaleFactorPercentage 必须如上表所述有效。

2.2.2.15 视野 2 配置控件

视野 2 配置控件将支持的对角线视场角度值指定为一个数值数组。 所有支持的值必须在理论最小值和最大值，1 度 - 360 度范围内。

如果设备想要支持连续的视野值，则需要报告所有支持的值。 例如，如果设备希望支持从 85 度到 60 度（步骤大小为 1）的对角字段，则此控件需要报告值数组 [85， 84， 83， 82， ...， 62， 61， 60]。

当视野 2 控件存在时，此控件必须可用来报告功能。

这是同步筛选器级别控制。

此控件由相机驱动程序映射到 KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2_CONFIGCAPS。

控件选择器	MSXU_CONTROL_FIELDOFVIEW2_CONFIG
强制请求	GET_INFO、GET_LEN、GET_RES、GET_MIN、GET_MAX、GET_DEF、GET_CUR
可选请求
wLength	4 个字节 + 计数 时间 4 个字节，其中 计数 是唯一的视野值的数量。

Offset	字段	大小	值	说明
0	dwDefaultFieldOfView	4	Number	默认对角视野必须是 FieldOfViewValues 数组中报告的值之一。
4	FieldOfViewValues[0]	4	Number	第一个视野值，此值必须是最宽的 FoV（视野）值。
…	…	…	…	…
4 + 4*（计数-1）	FieldOfViewValues [Count -1]	4	Number	最后一个视野值，此值必须是最窄的 FoV 值。

以下内容适用：

• GET_LEN 请求应报告负载的整个大小。

• GET_INFO 请求应报告 1。 此值指示仅支持 GET_CUR 的同步控件。

• GET_CUR 请求应按降序报告包含默认 FoV 和受支持 FoV 值的数组的数据。 该结构的字段定义如上。

• GET_DEF 请求应报告与 GET_CUR 相同。

• GET_MIN、GET_MAX 和 GET_RES 请求未使用，但应返回与 GET_CUR 相同的值。

• 不支持 SET_CUR 请求。

视野值必须按降序排列，例如，最宽的视野字段是第一个，最窄的字段是最后一个。

2.2.2.16 视野 2 控件

此控件指定相机在流式传输时使用的基本视野。 此控件可在流式处理之前或流式处理期间应用。

此控件可用于所有类型的相机，与流媒体类型无关。

此控件允许主机软件查询和控制与相机关联的视野。

这是一个全局控件，它影响与视频控制接口关联的所有视频流式处理接口上的所有端点。 它调整 ISP（图像信号处理器）使用的像素（或传感器）数据的源。 这包括方法 2 和方法 3 静态捕获引脚。

这是同步筛选器级别控制。

此控件由相机驱动程序映射到 KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2。

控件选择器	MSXU_CONTROL_FIELDOFVIEW2
强制请求	GET_INFO、GET_LEN、GET_RES、GET_MIN、GET_MAX、GET_DEF、GET_CUR、SET_CUR
可选请求
wLength	4

Offset	字段	大小	值	说明
0	dwValue	4	Number	以度为单位的对角视野值。

以下内容适用：

• GET_LEN 请求应报告值 4。

• GET_INFO 请求应报告 3。 此值指示支持 GET_CUR 和 SET_CUR 的同步控件。

• GET_MIN 请求应报告字段 dwValue 设置为最低支持的视野值。

• GET_RES 请求应报告字段 dwValue 设置为 0。 此请求当前未使用。

• GET_MAX 请求应报告字段 dwValue 设置为最大支持的视野值。

• GET_DEF 请求应将字段 dwValue 设置为默认的视野值。

• GET_CUR 请求应将字段 dwValue 设置为当前视野值。

• 收到 SET_CUR 请求时，相机将设置其视野以匹配给定的 dwValue。

• 如果相机实现 CT_ZOOM_RELATIVE_CONTROL 和/或 CT_ZOOM_ABSOLUTE_CONTROL，则在调用 MSXU_CONTROL_FIELDOFVIEW2 SET_CUR时，这些控件应重置为其默认值。

如果相机实现 MSXU_CONTROL_DIGITALWINDOW，则当设置新的视野值时，它应反映窗口更改。 反之亦然，视野反映应通过数字窗口所做的更改。 有关详细信息，请参阅KSPROPERTY_CAMERACONTROL_EXTENDED_ FIELDOFVIEW2。

2.2.3 元数据

标准格式帧元数据的设计基于 Windows 10 的 UVC 自定义元数据设计。 在 Windows 10 中，通过为相机驱动程序使用自定义 INF，UVC 可支持自定义元数据（注：相机驱动程序可以基于 Windows USBVIDEO.SYS，但需要为给定的硬件使用自定义 INF，以便通过元数据）。 如果 MetadataBufferSizeInKB<PinIndex> 注册表项存在且为非零，则该引脚支持自定义元数据，并且该值指示用于元数据的缓冲区大小。 该 <PinIndex> 字段指示视频引脚索引的 0 的索引。

在 Windows 10 版本 1703 中，相机驱动程序可以通过包含以下 AddReg 条目来指示对 Microsoft 标准格式元数据的支持：

StandardFormatMetadata<PinIndex>：REG_DWORD： 0x0 (NotSupported) 到 0x1 （支持）

DevProxy 将读取此注册表项，并通过为 KSSTREAM_METADATA_INFO 结构的 Flags 字段中设置标志 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 字段由以下枚举定义的标识符填充，其中包含定义完善的标识符和自定义标识符 (identifiers >= 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 视频类驱动程序帧的有效负载规范定义：

Payload 标头

下面是基于帧的格式的有效负载标头格式的说明。

HLE（标头长度）字段

标头长度字段指定标头的长度（以字节为单位）。

位字段标头字段

FID：帧标识符

• 此位在每个帧开始边界处切换，并保留帧其余部分的常量。

EOF：End of Frame（帧结束）

• 此位指示视频帧的末尾，并在属于帧的最后一个视频示例中设置。 使用此位是一种优化，目的是减少帧传输完成时的延迟，属于可选项。

PTS：Presentation Time Stamp（演示时间戳）

• 设置时，此位指示存在 PTS 字段。

SCR：源时钟参考

• 设置时，此位指示存在 SCR 字段。

RES：Reserved（保留）

• 将 设置为 0。

STI：Still Image（静止图像）

• 设置时，此位将视频示例标识为属于静态图像。

ERR：Error Bit（错误位）

• 设置时，此位指示设备流式处理中的错误。

EOH：End of Header（标头结尾）

• 设置时，此位指示 BFH 字段的末尾。

PTS：Presentation Time Stamp（演示文稿时间戳），大小：4 字节，值：数字

• 当在 BFH[0] 字段中设置 PTS 位时，会出现 PTS 字段。 请参阅适用于视频设备的 USB 设备类定义中的第 2.4.3.3 节“视频和静态图像有效负载标头”。

SCR：Source Clock Reference（源时钟参考），大小：6 字节，值：数字

• 当在 BFH[0] 字段中设置 SCR 位时，会出现 SCR 字段。 请参阅适用于视频设备的 USB 设备类定义中的第 2.4.3.3 节“视频和静态图像有效负载标头”。

现有 UVC 驱动程序中的 HLE 字段固定为 2 个字节（不存在 PTS/SCR）或最多 12 个字节（存在 PTS/SCR）。 但是，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;

标志字段指示结构中的哪些后续字段已填充并具有有效数据。 标志字段不得因帧而异。 当前定义了以下标志：

#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。

曝光时间字段包含捕获帧时应用于传感器的曝光时间（以 100 ns 为单位）。 这显示为相应 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.9 节中定义的元数据控制报告，在其缓冲区要求中包含存储该有效载荷所需的空间。