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

在 Windows 8.1 中，UWP 设备应用允许设备制造商自定义浮出控件，这些浮出控件在某些相机应用中显示更多相机选项。 This topic introduces the More options flyout that's displayed by the CameraCaptureUI API, and shows how the C# version of the UWP device app for camera sample replaces the default flyout with a custom flyout. 若要了解有关 UWP 设备应用的一般详细信息，请参阅 UWP 设备应用简介。

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

相机的更多选项

The more camera options experience is the functionality that a UWP device app provides when another app, a UWP app, captures or previews video from the camera by using the CameraCaptureUI API. It is accessible through the More options link in the Camera options window. 它不是全屏显示，而是显示在浮出控件中，该控件用于显示当用户单击或点击外部时关闭的轻型上下文用户界面。

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

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

若要调用浮出控件以获取更多相机选项，请执行以下作：

1. Open a UWP app that uses the CameraCaptureUI API (the CameraCaptureUI sample, for example)

2. Tap the Options button in the UI

3. This opens a Camera options flyout that shows basic options for setting resolution and video stabilization

4. On the Camera options flyout, tap More options

5. The More options flyout opens

   • The default flyout appears when no UWP device app for the camera is installed

   • A custom flyout appears when a UWP device app for the camera is installed

此图像显示自定义浮出控件示例旁边的更多相机选项的默认浮出控件。

Prerequisites

准备工作：

1. 设置开发电脑。 See Getting started for info about downloading the tools and creating a developer account.

2. 将应用与应用商店相关联。 有关该应用的信息，请参阅 “创建 UWP 设备应用 ”。

3. 为将它与应用关联的打印机创建设备元数据。 有关此内容的详细信息，请参阅 “创建设备元数据 ”。

4. 为应用的主页生成 UI。 可以从“开始”启动启动所有 UWP 设备应用，其中将显示它们全屏。 使用“开始”体验以与设备的特定品牌和功能匹配的方式突出显示产品或服务。 它可以使用的 UI 控件类型没有特殊限制。 若要开始设计全屏体验，请参阅 Microsoft应用商店设计原则。

步骤 1：注册扩展

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

You can add the camera settings extension on the Declarations tab of the Manifest Designer in Microsoft Visual Studio. 还可以使用 XML（文本）编辑器手动编辑应用包清单 XML。 Right-click the Package.appxmanifest file in Solution Explorer for editing options.

This example shows the camera settings extension in the Extension element, as it appears in the app package manifest file, 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

在构建应用之前，应与设计人员和营销团队合作，设计用户体验。 用户体验应投影公司的品牌方面，并帮助你与用户建立连接。

Design guidelines

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

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

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

• 调整窗口大小以调整为高和窄布局的指南

Flyout dimensions

显示更多相机选项的浮出控件高 625 像素，宽 340 像素。 The area containing the More options text at the top is provided by Windows and is approximately 65 pixels high, leaving 560 pixels for the viewable area of the custom flyout. 自定义浮出控件的宽度不应超过 340 像素。

Suggested effects

• Color effects. 例如，灰度、败血症音调或将整个图片太阳化。

• Face-tracking effects. 在图片中识别人脸和覆盖物（如帽子或一对眼镜）将添加到其顶部。

• Scene modes. 这些是不同照明条件的预设曝光和焦点模式。

Suggested settings

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

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

Restrictions

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

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

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

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

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

步骤 3：处理激活

如果你的应用已声明相机设置扩展，它必须实现一种方法 OnActivated 来处理应用激活事件。 This event is triggered when a UWP app, using the CameraCaptureUI class, calls the CameraOptionsUI.Show method. 应用激活是在应用启动时，应用可以选择启动哪个页面。 对于已声明相机设置扩展的应用，Windows 会在 Activated 事件参数中传递视频设备：Windows.ApplicationModel.Activation.IActivatedEventArgs。

A UWP device app can determine that the activation is intended for camera settings (that someone just tapped More options on the Camera options dialog) when the event argument's kind property is equal to Windows.ApplicationModel.Activation.ActivationKind.CameraSettings.

This example shows the activation event handler in the OnActivated method, as it appears in the App.xaml.cs file. The event arguments are then cast as Windows.ApplicationModel.Activation.CameraSettingsActivatedEventArgs and sent to the Initialize method of the custom flyout (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：控制设置和效果

When the Initialize method of the custom flyout (DeviceAppPage.xaml.cs) is called, the video device is passed to the flyout through the event arguments. 这些参数公开用于控制相机的属性：

• The args.VideoDeviceController property provides an object of type Windows.Media.Devices.VideoDeviceController. 此对象提供用于调整标准设置的方法。

• The args.VideoDeviceExtension property is a pointer to the camera driver MFT. 如果未公开驱动程序 MFT 接口，则此属性将为 null。 有关相机驱动程序 MFT 的详细信息，请参阅 创建相机驱动程序 MFT。

This example shows a portion of the Initialize method, as it appears in the DeviceAppPage.xaml.cs file. 在这里，将创建视频设备控制器（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;
    }
    // . . .
    // . . .
    // . . .

The camera driver MFT is demonstrated in the Driver MFT sample. 有关相机驱动程序 MFT 的详细信息，请参阅 创建相机驱动程序 MFT。

步骤 5：应用更改

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

This example shows the Changed methods that apply changes to the video device controller and the camera driver MFT, as they appear in the DeviceAppPage.xaml.cs file.

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));
}

测试应用程序

This section describes how to install a UWP device app that provides a custom flyout for More options of a camera, as demonstrated in the UWP device app for camera sample.

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

• 需要打印机的设备元数据包的副本，才能将设备应用信息添加到其中。 如果没有设备元数据，可以使用 设备元数据创作向导 生成它，如主题 “为 UWP 设备应用创建设备元数据”中所述。

以下步骤生成应用并安装设备元数据。

1. 启用测试签名。

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

   2. From the Tools menu, select Enable Test Signing.

2. 重新启动计算机

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

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

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

   Note

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

   1. 如果设备元数据创作向导尚未打开，请双击 DeviceMetadataWizard.exe从%ProgramFiles（x86）%\Windows Kits\8.1\bin\x86 启动它。

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

   3. In the Open dialog box, locate the device metadata package associated with your UWP device app. (It has a devicemetadata-ms file extension.)

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

   5. When you're done, click Next until you get to the Finish page.

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

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

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

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

测试示例

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

• 适用于相机的 UWP 设备应用示例
• 相机捕获 UI 示例
• 驱动程序 MFT 示例

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