如何使用 UWP 设备应用自定义相机选项

在 Windows 8.1 中，UWP 设备应用允许设备制造商在某些相机应用中自定义浮出控件来显示更多相机选项。 本主题介绍由 CameraCaptureUI API 显示的更多选项浮出控件，并演示 C# 版本的适用于相机的 UWP 设备应用示例如何将默认浮出控件替换为自定义浮出控件。 要了解有关 UWP 设备应用的一般详细信息，请参阅初识 UWP 设备应用。

注意

在 Windows 8.1 中，内置相机应用不显示“更多选项”按钮，因此无法显示 UWP 设备应用以显示更多相机选项。 但是，所有 UWP 应用都可使用的 CameraCaptureUI 类有一个“更多选项”按钮，并可从中显示 UWP 设备应用。

C# 版本的适用于相机的 UWP 设备应用示例使用 DeviceAppPage.xaml 页面来演示有关更多选项的自定义浮出控件的 UI。 该示例还使用相机驱动程序 MFT（媒体基础转换）应用相机效果。 有关此内容的详细信息，请参阅创建相机驱动程序 MFT。

注意

本主题中所示的代码示例基于 C# 版本的适用于相机的 UWP 设备应用示例。 此示例还有 JavaScript 和 C++ 版本。 下载示例以查看最新版本的代码。

相机的更多选项

更多相机选项体验是 UWP 设备应用在另一个 UWP 应用使用 CameraCaptureUI API 从相机捕获或预览视频时提供的功能。 可通过相机选项窗口中的更多选项链接访问它。 它不是全屏显示，而是显示在浮出控件中，该浮出控件用于显示当用户单击或点击外部时关闭的轻型上下文用户界面。

此体验可用于突出显示相机的差异化功能，例如应用自定义视频效果的功能。

如果没有为相机安装 UWP 设备应用，Windows 将提供默认的更多相机选项体验。 如果 Windows 检测到已为相机安装了 UWP 设备应用，并且该应用已选择加入 windows.cameraSettings 扩展，则你的应用将替换 Windows 提供的默认体验。

要调用有关更多选项的浮出控件，请执行以下操作：

1. 打开使用 CameraCaptureUI API 的 UWP 应用（例如，CameraCaptureUI sample）

2. 点击 UI 中的“选项”按钮

3. 这将打开一个相机选项浮出控件，其中显示用于设置分辨率和视频稳定的基本选项

4. 在相机选项浮出控件上，点击“更多选项”

5. 此时会打开更多选项浮出控件

   • 在没有为相机安装 UWP 设备应用时，将显示默认浮出控件

   • 如果已为相机安装了 UWP 设备应用，将显示自定义浮出控件

此图像显示有关更多选项的默认浮出控件以及自定义浮出控件的示例。

先决条件

准备工作：

1. 设置你的开发电脑。 有关下载工具和创建开发人员帐户的信息，请参阅入门。

2. 将应用与商店相关联。 请参阅创建 UWP 设备应用以获取相关信息。

3. 为你的打印机创建设备元数据，将其与你的应用关联起来。 请参阅创建设备元数据以了解详细信息。

4. 为你的应用的主页构建 UI。 所有 UWP 设备应用都可以从“开始”启动，并以全屏方式显示。 使用“开始”体验，以符合设备特定品牌和功能的方式突出你的产品或服务。 它可以使用的 UI 控件类型没有特殊限制。 要开始设计全屏体验，请参阅 Microsoft Store 设计原则。

步骤 1：注册扩展

要让 Windows 识别应用可以提供有关更多相机选项的自定义浮出控件，它必须注册相机设置扩展。 此扩展在 Extension 元素中声明，其属性 Category 设置为值 windows.cameraSettings。 在 C# 和 C++ 示例中，Executable 属性设置为 DeviceAppForWebcam.exe，属性 EntryPoint 设置为 DeviceAppForWebcam.App。

可以在 Microsoft Visual Studio 中清单设计器的“声明”选项卡上添加相机设置扩展。 还可以使用 XML（文本）编辑器手动编辑应用包清单 XML。 在“解决方案资源管理器”中，右键单击 Package.appxmanifest 文件。

此示例显示 Extension 元素中的相机设置扩展，因为它显示在应用包清单文件 Package.appxmanifest 中。

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest">
  <Identity Name="Microsoft.SDKSamples.DeviceAppForWebcam.CPP" Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" Version="1.0.0.0" />
  <Properties>
    <DisplayName>DeviceAppForWebcam CPP sample</DisplayName>
    <PublisherDisplayName>Microsoft Corporation</PublisherDisplayName>
    <Logo>Assets\storeLogo-sdk.png</Logo>
  </Properties>
  <Prerequisites>
    <OSMinVersion>6.3.0</OSMinVersion>
    <OSMaxVersionTested>6.3.0</OSMaxVersionTested>
  </Prerequisites>
  <Resources>
    <Resource Language="x-generate" />
  </Resources>
  <Applications>
    <Application Id="DeviceAppForWebcam.App" Executable="$targetnametoken$.exe" EntryPoint="DeviceAppForWebcam.App">
      <VisualElements DisplayName="DeviceAppForWebcam CPP sample" Logo="Assets\squareTile-sdk.png" SmallLogo="Assets\smallTile-sdk.png" Description="DeviceAppForWebcam CPP sample" ForegroundText="light" BackgroundColor="#00b2f0">
        <DefaultTile ShortName="DeviceApp CPP" ShowName="allLogos" />
        <SplashScreen Image="Assets\splash-sdk.png" BackgroundColor="#00b2f0" />
      </VisualElements>
      <Extensions>
        <Extension Category="windows.cameraSettings" Executable="DeviceAppForWebcam.exe" EntryPoint="DeviceAppForWebcam.App" />
      </Extensions>
    </Application>
  </Applications>
</Package>

步骤 2：构建 UI

在构建应用之前，应与设计人员和营销团队合作来设计用户体验。 用户体验应体现公司的品牌形象，帮助你与用户建立联系。

设计指南

在设计自定义浮出控件之前，请务必查看 UWP 应用浮出控件指南。 这些指南有助于确保浮出控件提供与其他 UWP 应用一致的直观体验。

对于应用的主页，请记住，Windows 8.1 可以在一个监视器上显示不同大小的多个应用。 请参阅以下指南，详细了解应用如何在不同屏幕大小、窗口大小和方向之间正常重排。

• 窗口大小和屏幕缩放指南

• 调整窗口大小以适应高窄布局的指南

浮出控件尺寸

显示更多相机选项的浮出控件高 625 像素，宽 340 像素。 顶部包含“更多选项”文本的区域由 Windows 提供，高度约为 65 像素，因此为自定义浮出控件保留的可视区域为 560 像素。 自定义浮出控件的宽度不应超过 340 像素。

注意

如果自定义浮出控件高度超过 560 像素，则用户可以滑动或滚动以查看位于可视区域上方或下方的浮出控件部分。

建议的效果

• 颜色效果。 例如，灰度、棕色调或日晒整个画面。

• 人脸跟踪效果。 即在图片中识别出一张脸，然后在上面添加一个覆盖物，如一顶帽子或一副眼镜。

• 场景模式。 这些都是针对不同光线条件预设的曝光和对焦模式。

建议的设置

• UWP 设备应用的自定义浮出控件可以提供一个开关来启用硬件实现的设置，例如制造商提供的色彩校正方案。

• 实现补充 UWP 设备应用公开的其他设置的基本属性。 例如，许多设备可能会公开用于调整亮度、对比度、闪烁、焦点和曝光的控件，但实现 TrueColor 以自动调整亮度和对比度的设备可能不需要提供这些设置。

限制

• 当 UWP 设备应用未进行流式传输或捕获时，请勿从主应用（通过调用 CameraOptionsUI.Show 方法）打开 UWP 设备应用的自定义浮出控件。

• 请勿从 UWP 设备应用的自定义浮出控件提供预览或以其他方式获取视频流的所有权。 自定义浮出控件旨在充当另一个捕获视频的应用的助手。 捕获应用拥有视频流的所有权。 不应尝试使用低级别 API 访问视频流。 这可能会导致意外行为，即捕获应用无法访问流。

• 不要在自定义浮出控件中调整分辨率。

• 不要尝试在用于自定义浮出控件的区域之外显示弹出窗口、通知或对话框。 不允许使用这些类型的对话。

• 不要在自定义浮出控件中启动音频或视频捕获。 自定义浮出控件旨在扩展另一个正在捕获视频的应用，而不是启动捕获本身。 此外，捕获音频或视频可能会触发系统对话框，而自定义窗口内不允许弹出对话框。

步骤 3：处理激活

如果你的应用已声明相机设置扩展，它必须实现一种 OnActivated 方法来处理应用激活事件。 当使用 CameraCaptureUI 类的 UWP 应用调用 CameraOptionsUI.Show 方法时，将触发该事件。 应用激活是在应用启动时，应用可以选择启动哪个页面。 对于已声明相机设置扩展的应用，Windows 会在激活事件参数中传递视频设备：Windows.ApplicationModel.Activation.IActivatedEventArgs。

当事件参数的 kind 属性等于 Windows.ApplicationModel.Activation.ActivationKind.CameraSettings 时，UWP 设备应用可以确定激活适用于相机设置（有人刚刚点击了“相机选项”对话框中的“更多选项”）设置。

本示例显示 OnActivated 方法中的激活事件处理程序，如 App.xaml.cs 文件中所示。 然后，事件参数将强制转换为 Windows.ApplicationModel.Activation.CameraSettingsActivatedEventArgs 并发送到自定义浮出控件的 Initialize 方法 (DeviceAppPage.xaml.cs)。

protected override void OnActivated(IActivatedEventArgs args)
{
    if (args.Kind == ActivationKind.CameraSettings)
    {
        base.OnActivated(args);
        DeviceAppPage page = new DeviceAppPage();
        Window.Current.Content = page;
        page.Initialize((CameraSettingsActivatedEventArgs)args);

        Window.Current.Activate();
    }
}

步骤 4：控制设置和效果

调用自定义浮出控件 (DeviceAppPage.xaml.cs) 的 Initialize 方法时，视频设备将通过事件参数传递到浮出控件。 这些参数公开用于控制相机的属性：

• args.VideoDeviceController 属性提供类型为 Windows.Media.Devices.VideoDeviceController 的对象。 此对象提供用于调整标准设置的方法。

• args.VideoDeviceExtension 属性是指向相机驱动程序 MFT 的指针。 如果未公开驱动程序 MFT 接口，则此属性将为 null。 有关相机驱动程序 MFT 的详细信息，请参阅创建相机驱动程序 MFT。

本示例显示 Initialize 方法的一部分，如 DeviceAppPage.xaml.cs 文件中所示。 在这里，创建了视频设备控制器（videoDevController 对象）和相机驱动程序 MFT（lcWrapper 对象），浮出控件将填充当前相机设置。

public void Initialize(CameraSettingsActivatedEventArgs args)
{
    videoDevController = (VideoDeviceController)args.VideoDeviceController;

    if (args.VideoDeviceExtension != null)
    {
        lcWrapper = new WinRTComponent();
        lcWrapper.Initialize(args.VideoDeviceExtension);
    }

    bool bAuto = false;
    double value = 0.0;

    if (videoDevController.Brightness.Capabilities.Step != 0)
    {
        slBrt.Minimum = videoDevController.Brightness.Capabilities.Min;
        slBrt.Maximum = videoDevController.Brightness.Capabilities.Max;
        slBrt.StepFrequency = videoDevController.Brightness.Capabilities.Step;
        videoDevController.Brightness.TryGetValue(out value);
        slBrt.Value = value;
    }
    else
    {
        slBrt.IsEnabled = false;
    }
    if (videoDevController.Brightness.Capabilities.AutoModeSupported)
    {
        videoDevController.Brightness.TryGetAuto(out bAuto);
        tsBrtAuto.IsOn = bAuto;
    }
    else
    {
        tsBrtAuto.IsOn = false;
        tsBrtAuto.IsEnabled = false;
    }

    if (videoDevController.Contrast.Capabilities.Step != 0)
    {
        slCrt.Minimum = videoDevController.Contrast.Capabilities.Min;
        slCrt.Maximum = videoDevController.Contrast.Capabilities.Max;
        slCrt.StepFrequency = videoDevController.Contrast.Capabilities.Step;
        videoDevController.Contrast.TryGetValue(out value);
        slCrt.Value = value;
    }
    else
    {
        slCrt.IsEnabled = false;
    }
    // . . .
    // . . .
    // . . .

驱动程序 MFT 示例中演示了相机驱动程序 MFT。 有关相机驱动程序 MFT 的详细信息，请参阅创建相机驱动程序 MFT。

步骤 5：应用更改

当对浮出控件进行更改时，相应的控件的 Changed 事件用于将更改应用于视频设备控制器（videoDevController 对象）和相机驱动程序 MFT（lcWrapper 对象）。

本示例显示了将更改应用到视频设备控制器和相机驱动程序 MFT 的 Changed 方法，它们显示在 DeviceAppPage.xaml.cs 文件中。

protected void OnBrtAutoToggleChanged(object sender, RoutedEventArgs e)
{
    videoDevController.Brightness.TrySetAuto(tsBrtAuto.IsOn);
    slBrt.IsEnabled = !tsBrtAuto.IsOn;
}

protected void OnBrtSliderValueChanged(object sender, RoutedEventArgs e)
{
    videoDevController.Brightness.TrySetValue(slBrt.Value);
}

protected void OnCrtAutoToggleChanged(object sender, RoutedEventArgs e)
{
    videoDevController.Contrast.TrySetAuto(tsCrtAuto.IsOn);
    slCrt.IsEnabled = !tsCrtAuto.IsOn;
}

protected void OnCrtSliderValueChanged(object sender, RoutedEventArgs e)
{
    videoDevController.Contrast.TrySetValue(slCrt.Value);
}

protected void OnFocusAutoToggleChanged(object sender, RoutedEventArgs e)
{
    videoDevController.Focus.TrySetAuto(tsFocusAuto.IsOn);
    slFocus.IsEnabled = !tsFocusAuto.IsOn;
}

protected void OnFocusSliderValueChanged(object sender, RoutedEventArgs e)
{
    videoDevController.Focus.TrySetValue(slFocus.Value);
}

protected void OnExpAutoToggleChanged(object sender, RoutedEventArgs e)
{
    videoDevController.Exposure.TrySetAuto(tsExpAuto.IsOn);
    slExp.IsEnabled = !tsExpAuto.IsOn;
}

protected void OnExpSliderValueChanged(object sender, RoutedEventArgs e)
{
    videoDevController.Exposure.TrySetValue(slExp.Value);
}

protected void OnEffectEnabledToggleChanged(object sender, RoutedEventArgs e)
{
    if (tsEffectEnabled.IsOn)
    {
        lcWrapper.Enable();
    }
    else
    {
        lcWrapper.Disable();
    }
    slEffect.IsEnabled = tsEffectEnabled.IsOn;
}

protected void OnEffectSliderValueChanged(object sender, RoutedEventArgs e)
{
    lcWrapper.UpdateDsp(Convert.ToInt32(slEffect.Value));
}

测试应用

本部分介绍如何安装为相机的“更多选项”提供自定义浮出控件的 UWP 设备应用，如适用于相机的 UWP 设备应用示例所示。

在测试 UWP 设备应用之前，必须使用设备元数据将其链接到相机。

• 你需要一份打印机的设备元数据包副本，以便在其中添加设备应用信息。 如果没有设备元数据，可以使用设备元数据创作向导构建，如主题为 UWP 设备应用创建设备元数据所述。

注意

要使用设备元数据创作向导，必须先安装 Microsoft Visual Studio Professional、Microsoft Visual Studio Ultimate 或适用于 Windows 8.1 的独立 SDK，然后才能完成本主题中的步骤。 安装 Microsoft Visual Studio Express for Windows 会安装不包含向导的 SDK 版本。

以下步骤构建你的应用并安装设备元数据。

1. 启用测试签名。

   1. 通过双击 DeviceMetadataWizard.exe，从 %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86 启动设备元数据创作向导

   2. 在“工具”菜单中，选择“启用测试签名”。

2. 重新启动计算机

3. 通过打开解决方案 (.sln) 文件生成解决方案。 按 F7 或在示例加载后从顶部菜单中转到“生成-生成解决方案”。>

4. 断开连接并卸载打印机。 此步骤是必需的，以便 Windows 下次检测设备时读取更新的设备元数据。

5. 编辑和保存设备元数据。 要将设备应用链接到你的设备，必须将设备应用与你的设备相关联。

   注意

   注意：如果尚未创建设备元数据，请参阅为 UWP 设备应用创建设备元数据。

   1. 如果设备元数据创作向导尚未打开，请双击 DeviceMetadataWizard.exe 从 %ProgramFiles(x86)%\Windows Kits\8.1\bin\x86 将其打开。

   2. 单击“编辑设备元数据”。 这样，就可以编辑现有的设备元数据包。

   3. 在“打开”对话框中，找到与 UWP 设备应用关联的设备元数据包。 （它具有 devicemetadata-ms 文件扩展名。）

   4. 在“指定 UWP 设备应用信息”页上，在“UWP 设备应用”框中输入 Microsoft Store 应用信息。 单击“导入 UWP 应用清单文件”，自入“包名称”、“发布者名称”和“UWP 应用 ID”。

   5. 完成后，单击“下一步”，直到进入“完成”页。

   6. 在“查看设备元数据包”页上，确保所有设置都正确，并选择“将设备元数据包复制到本地计算机上的元数据存储”复选框中。 然后单击保存。

6. 重新连接设备，以便 Windows 在设备连接时读取更新的设备元数据。

   • 如果你有外部相机，只需连接相机即可。

   • 如果你有内部相机，请在“设备和打印机”文件夹中刷新电脑。 使用设备管理器扫描硬件更改。 检测到设备时，Windows 应读取更新的元数据。

注意

有关安装相机驱动程序 MFT 的信息，请参阅创建相机驱动程序 MFT 中的“测试”部分。

测试示例

要测试相机选项体验，请先下载以下示例：

• 适用于相机的 UWP 设备应用示例

• 相机捕获 UI 示例

• 驱动程序 MFT 示例

然后，按照驱动程序 MFT 示例页上提供的示例测试说明进行操作。