相机配套应用

本文介绍配套应用,它们是相机制造商的扩展性功能,可用于生成能配置相机并调整默认图像设置的自定义应用程序。

介绍

Windows 11 提供相机配套应用框架,它允许制造商开发具有以下功能的应用程序:

  • 可显示并/或修改相机设置页面支持的相同默认值设置(例如,亮度、对比度、背景效果等)。

  • 可注册、更新或删除 Windows 已知但未通过相机设置页面(例如,Hue 控件)予以公开的其他相机控件的默认值设置。

  • 可注册、更新或删除制造商专有相机控件的默认值设置(例如,针对相机制造商的自定义照明调整效果的开/关控件)。

当相机注册关联的配套应用时,会向相机设置页面添加一个条目。 如果已安装此应用,则可从相机设置页面启动它,否则会显示 Microsoft Store 的链接以便下载它。

配套应用具有对 API 的特殊访问权限;借助该权限,应用可注册、更新或删除默认值;例如,相机设置页面。

术语和先决条件

术语 定义
伴侣应用 相机制造商开发的自定义应用程序;借助该应用程序,除相机设置页面之外,还允许配置和管理相机。
当前值 某一相机控件的值,而该控件当前在相机的 ISP 中处于活动状态,并保存在相机的临时内存中。
默认值 在特定电脑上针对特定用户帐户而存储到磁盘中并为特定相机而保存的某一相机控件的初始值。
HSA 硬件支持应用(Microsoft 所支持的框架)会在设备连接时自动从 Microsoft Store 下载并安装与硬件关联的应用。
NPU 神经处理单元,该专用硬件旨在处理具备高吞吐量和效率的人工智能工作负荷。
Windows Studio 效果 一组可用于具有 NPU 的特选 Windows 电脑的视频效果。
UVC USB 视频类,它是用于从 USB 连接的相机进行控制和流式传输的标准化接口。

配套应用要求

配套应用必须为附带包标识的打包应用程序。 配套应用还须在 Microsoft Store 上发布,从而可通过相机设置页面来引导客户安装该应用(如果尚未安装)。

没有包标识的传统桌面应用程序无法用作配套应用。

作为 HSA 的配套应用

无需将配套应用也配置为硬件支持应用,但强烈建议执行此操作。 HSA 是 Microsoft Store 中与特定硬件设备关联的特殊应用。 当该设备连接到电脑时,HSA 会在可用时自动从 Microsoft Store 下载并安装。

将配套应用与相机关联

相机制造商可通过用配套应用的程序包系列名称 (PFN) 填充特定的设备属性密钥来关联配套应用:

名称 类型 数据
SCSVCamPfn REG_SZ <PFN>

若要标识配套应用的 PFN,请从 PowerShell 运行 Get-AppxPackage,例如:

Get-AppxPackage -Name 配套应用名称

若要将配套应用关联到相机,请在 UVC 相机中使用 MSOS 描述符,或在相机驱动程序的 INF 中使用 AddReg 指令。 例如,使用 INF 文件来执行以下操作:

[SocCaptureSim.RearCamera.AddReg]

HKR,,SCSVCamPfn,,%AppPFN%

...

[Strings]

AppPFN="Contoso.CameraCompanion_xxxxxxxx00000"

当配套应用与某一相机关联时,相机设置页面会在该相机的特定设置页面的“相关设置”标题下包含该配套应用的链接。

如果已安装配套应用,则会显示用于“打开 {配套应用名称}”的链接。 单击后,此应用便会启动。

如果尚未安装配套应用,则会显示一个用于启动 Microsoft Store 以便下载并安装该应用的链接。

一台相机只能有一个与之关联的配套应用。

从相机设置页面启动配套应用

当相机设置页面启动配套应用时,相机的符号链接将通过 Application.OnLaunched 参数并作为上下文来传递。

参数 类型 数据
cameraId 字符串 符号链接

此功能允许配套应用在以下情况下显示正确相机的设置:

  1. 单个配套应用支持单个系统上的多个相机(例如,OEM 提供的应用程序支持平板电脑上的前置与后置摄像头)。

  2. 一个客户有两个相同(或同一品牌)的相机连接到由同一配套应用所管理的系统。

从配套应用启动相机设置页面

配套应用可使用深层链接 URI 来启动 Windows 相机设置页面。 有关详细信息,请参阅启动相机设置页

从配套应用配置默认值

配套应用可使用 IMFCameraConfigurationManager API 来配置当前用户的默认值配置。 此 API 允许配套应用读取任意已配置的默认值(例如,用户通过相机设置页面设置的默认值)、修改任意默认值、注册新的默认值或删除已保存的默认值。

默认值会在系统的数据库中注册为一对 KS 属性 GUID 与相应的值。 如此一来,该体系结构便与 KS 属性的定义无关。 凭借此灵活性,配套应用便可设置、编辑或删除以下任意设置的默认值:

  • 也可通过相机设置页面来配置的某些设置(例如,亮度、对比度、背景效果等)

  • 对于 Windows 已知但未通过相机设置页面予以公开的其他相机控件(例如,Hue 控件)的设置

  • 制造商专有相机控件(例如,针对相机制造商自定义照明调整效果的开/关控件)的设置

从配套应用配置亮度

可通过几种方法来控制相机所捕获图像的有效亮度。 例如,可通过向图像应用简易增益来提高亮度,同时也可通过延长相机的曝光时间来提高亮度。

Windows 支持采用简易增益控件设计的旧版亮度控件 (KSPROPERTY_VIDEOPROCAMP_BRIGHTNESS)。 Windows 还支持曝光补偿控制 (KSPROPERTY_CAMERACONTROL_EXTENDED_EVCOMPENSATION),而该控件旨在控制相机的自动曝光算法的正曝光值偏差或负曝光值偏差。

无论相机使用哪个亮度控件,它均应在相机中实现,以便当“居中”时亮度处于中性状态,且客户可通过提高或降低该值来应用偏移量。 为实现最佳图像质量,强烈建议相机能支持曝光补偿控件;如此一来,当客户在相机设置页面或配套应用中调整亮度控件时,则可控制相机在曝光时应用固定的正偏差或负偏差,而从不考虑照明条件。

有关详细信息,请参阅相机设置页面以了解相机设置页面上的亮度控件的行为(具体取决于相机所实现的控件)。 如果配套应用还提供亮度滑块,则请务必复制此逻辑以确保在相机设置页面中的亮度滑块与配套应用之间进行同步。

下面链接的配套应用示例包括了此逻辑的参考实现。

监视是否出现实时当前值更改

如果配套应用与相机设置页面同时运行,客户则可使用相机设置页面来更改默认值,而配套应用则可同时在共享模式下运行以显示预览。 在此情况下,配套应用需监视这些控件的默认值是否出现更改,以便该应用能保持同步。

为此,配套应用可使用 IMFCameraControlMonitor 来监视所关注控件(KS 属性)的当前值是否出现更改。 由于以下原因,可能会出现此类更改:

  • 相机应用程序(例如 Microsoft Teams)正在使用相机并更改某一控件的当前值。

  • 相机设置页面正在使用相机并更改某一控件的默认值(同时,此操作也会更新当前值)。

此 API 可用作触发器,从而使用 IMFCameraConfigurationManager API 来重新读取所关注控件的默认值,并在任意默认值发生更改时更新 UI。

配套应用示例

GitHub 提供了一个示例配套应用:CameraSettingsExternalSettingsApp 示例。 此示例演示了如何使用 IMFCameraConfigurationManager API 来更改对比度、亮度和背景分段的默认值。

GitHub 上的 ControlMonitorApp 示例应用程序演示了如何使用 IMFCameraControlMonitor API 来监视所关注控件是否出现更改。

另请参阅

Application.OnLaunched

像机设置页面

CameraSettingsExternalSettingsApp 示例

ControlMonitorApp 示例

Get-AppxPackage

硬件支持应用

IMFCameraConfigurationManager

IMFCameraControlMonitor

KSPROPERTY_VIDEOPROCAMP_BRIGHTNESS

KSPROPERTY_CAMERACONTROL_EXTENDED_EVCOMPENSATION

启动相机设置页

MSOS 描述符

打包应用程序