如何在您的应用中使用Extensions API将特效应用到照片上

Android CameraX 的设计旨在帮助您简化相机应用的开发工作。随着对 CameraX 不断的开发，相机应用的开发者们向我们展示了他们的激情和热忱，当前的 API 中已经融入了许多很棒的创意，例如值得称赞的 CameraX Extensions API。最近我们采纳了开发者社区的意见，对扩展进行了重构，如今有了新的 ExtensionsManager，您只需两行代码就可以使用这些扩展！

本文将介绍如何在您的应用中使用 Extensions API。

• Android CameraX
  https://android-developers.googleblog.com/2019/05/whats-new-with-android-jetpack.html
• ExtensionsManager
  https://developer.android.google.cn/reference/androidx/camera/extensions/ExtensionsManager

CameraX Extensions

Android 设备配备了强大的相机，制造商们投入了大量精力将众多前沿的功能特性或特效融入这些相机设备中。过去，这些强大的功能只能由设备的原生相机应用提供。如今，凭借 CameraX Extensions API，第三方开发者可以通过一个通用的、简单的接口来访问这些强大的相机功能。

CameraX Extensions 涵盖的内容

1.0.0 版本的 CameraX Extensions 包括一些最常见的内置相机特效:

• BOKEH (焦外成像): 在人像模式下拍摄照片时，让前景人物更清晰。
• HDR (高动态范围):拍照时使用不同的自动曝光 (AE) 配置，以获得最佳效果。
• NIGHT (夜间):在低照度环境下 (通常是在夜间) 捕获最佳静态图像。
• FACE RETOUCH (脸部照片修复):拍摄静态图像时，修饰脸部肤色、轮廓等。
• AUTO (自动):根据周围的景色自动调整最终图像。

让我们来看几组在 Android 手机上拍摄的照片，拍照时分别启用和禁用了由 CameraX Extensions API 提供的特效。

NIGHT 模式例子

△图 3:右侧照片启用了 NIGHT 特效。

视觉上的差异是很明显的。您可以使用 CameraX Extensions API 在您自己的应用中实现这些图像的效果。

现在让我们看看如何将 CameraX 的 API 集成到您的应用中。

Extensions API

在现有的 CameraX 应用中，首先您可以引入 camera-extensions Jetpack 库来添加 CameraX Extensions:

dependencies {    // 与 Extensions 库版本号相匹配的 CameraX 核心库    implementation 'androidx.camera1.1.0-alpha08'    implementation 'androidx.camera1.1.0-alpha08'    implementation 'androidx.camera1.1.0-alpha08'
    // CameraX Extensions 库    implementation 'androidx.camera1.0.0-alpha28'
    // 其他依赖项    implementation('androidx.concurrent1.1.0')        …}

接下来，通过以下步骤集成 Extensions:

1. 获取 ExtensionsManager 实例:

   https://developer.android.google.cn/reference/androidx/camera/extensions/ExtensionsManager

2. 检查目标设备是否支持需要用到的扩展模式；
3. 获取一个启用扩展的 CameraSelector；

4. 使用启用扩展的 CameraSelector 调用 bindToLifecycle:

   https://developer.android.google.cn/reference/androidx/camera/lifecycle/ProcessCameraProvider#bindToLifecycle(androidx.lifecycle.LifecycleOwner,%20androidx.camera.core.CameraSelector,%20androidx.camera.core.UseCase...)

获取 ExtensionsManager 实例

第一步是用扩展库的 getInstance(Context) API 获得一个 ExtensionsManager 实例。这个 API 返回一个 ListenableFuture，我们可以在 Kotlin 挂起函数中使用 await() 来获取结果以避免阻塞主线程。(注意:在 ListenableFuture 上使用 await() 须引入 androidx.concurrent 1.1.0 依赖项。)

// 创建扩展管理器（使用 Jetpack Concurrent 库）valextensionsManager=ExtensionsManager.getInstance(context).await()

• getInstance(Context)

  https://developer.android.google.cn/reference/androidx/camera/extensions/ExtensionsManager#getInstance(android.content.Context)

• ExtensionsManager

  https://developer.android.google.cn/reference/androidx/camera/extensions/ExtensionsManager

通过 ExtensionsManager，您可以确定设备是否支持某一特定的扩展模式，并为其获取一个启用扩展的 CameraSelector。请注意以下几点:

• ExtensionsManager 是一个进程范围的全局资源: 一个进程中只存在一个 ExtensionsManager 实例。

• ExtensionsManager 始终存在:无论底层设备是否支持扩展，CameraX 都提供一个有效的 ExtensionsManager 实例。

检查扩展模式可用性

通过 ExtensionsManager，使用 isExtensionAvailable(CameraProvider, CameraSelector, int) 函数检查扩展的可用性:如果设备上存在任何经由 CameraSelector 过滤的相机支持所查询的扩展，则返回 true，否则返回 false。

        // 获取相机设备来检查是否支持扩展        val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
        // 检查是否支持 BOKEH        if (extensionsManager.isExtensionAvailable(                cameraProvider,                cameraSelector,                ExtensionMode.BOKEH            )) {            ...}

• isExtensionAvailable(CameraProvider, CameraSelector, int)

  https://developer.android.google.cn/reference/androidx/camera/extensions/ExtensionsManager#isExtensionAvailable(androidx.camera.core.CameraProvider,%20androidx.camera.core.CameraSelector,%20int)

获取启用扩展的 CameraSelector

一旦您确认了设备支持该扩展模式，就可以用 getExtensionEnabledCameraSelector(CameraProvider, CameraSelector, int) 函数获取一个启用扩展的 CameraSelector。此函数返回启用扩展的 CameraSelector，其包含关于指定扩展模式的所有详细信息。

val bokehCameraSelector = extensionsManager                          .getExtensionEnabledCameraSelector(cameraProvider,cameraSelector,ExtensionMode.BOKEH)

• getExtensionEnabledCameraSelector(CameraProvider, CameraSelector, int)

  https://developer.android.google.cn/reference/androidx/camera/extensions/ExtensionsManager#getExtensionEnabledCameraSelector(androidx.camera.core.CameraProvider,%20androidx.camera.core.CameraSelector,%20int)

使用启用扩展的 CameraSelector 调用 bindToLifecycle()

最后一步是使用 bindToLifecycle() 将您的用例与启用扩展的 CameraSelector 绑定。使用启用扩展的 CameraSelector 如同使用普通的 CameraSelector 一样，例如使用 DEFAULT_BACK_CAMERA 或 DEFAULT_FRONT_CAMERA。当使用启用扩展的 CameraSelector 绑定用例时，CameraX 会直接在相机上启用指定的扩展模式。例如，当绑定到 Preview 时，扩展效果被应用到预览中，或者应用到由所绑定的 ImageCapture 所捕获的图像上。

// 将开启了 BOKEH 的相机选择器绑定到用例上val imageCapture = ImageCapture.Builder().build()val preview = Preview.Builder().build()cameraProvider.bindToLifecycle(                lifecycleOwner,                bokehCameraSelector,                imageCapture,                preview)

• bindToLifecycle()
  https://developer.android.google.cn/reference/androidx/camera/lifecycle/ProcessCameraProvider#bindToLifecycle(androidx.lifecycle.LifecycleOwner,%20androidx.camera.core.CameraSelector,%20androidx.camera.core.UseCase...)

• DEFAULT_BACK_CAMERA
  https://developer.android.google.cn/reference/androidx/camera/core/CameraSelector#DEFAULT_BACK_CAMERA

• DEFAULT_FRONT_CAMERA
  https://developer.android.google.cn/reference/androidx/camera/core/CameraSelector#DEFAULT_FRONT_CAMERA

使用 Extensions API 的样例代码

Extensions API 示例的完整代码如下:

fun onCreate() {    lifecycleScope.launch {        // 创建 cameraProvider        val cameraProvider = ProcessCameraProvider.getInstance(context).await() 
        // 创建 extensionsManager（使用 Jetpack Concurrent 库）        val extensionsManager =                 ExtensionsManager.getInstance(context).await()
        // 获取相机设备来检查是否支持扩展                val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA
        // 检查是否支持 BOKEH        if (extensionsManager.isExtensionAvailable(                cameraProvider,                cameraSelector,                ExtensionMode.BOKEH            )) {            // 在启用不同扩展模式之前解除所有用例的绑定            cameraProvider.unbindAll()
//获取启用了BOKEH的相机选择器            val bokehCameraSelector = extensionsManager                    .getExtensionEnabledCameraSelector(                cameraProvider,                cameraSelector,                ExtensionMode.BOKEH            )
            // 将开启了 BOKEH 的相机选择器绑定到用例上            val imageCapture = ImageCapture.Builder().build()            val preview = Preview.Builder().build()            cameraProvider.bindToLifecycle(                lifecycleOwner,                bokehCameraSelector,                imageCapture,                preview            )        }    }}

Extensions API 对核心模块的依赖

CameraX Extensions API 是在 camera-extensions 库中实现的，并且它依赖 CameraX 核心模块 (core、camera2 和 lifecycle)。使用 CameraX Extensions 时，请务必使用与您正在使用的 CameraX 核心模块相同的发布包中的版本。例如，要使用 camera-extensions:1.0.0-alpha28，则您必须在应用的依赖列表中包含 1.0.0-alpha08 版本的 camera-lifecycle、camera-core 和 camera-camera2，因为它们是于 2021 年 8 月 18 日在同一软件包中发布的。

• 相同的发布包
  https://developer.android.google.cn/jetpack/androidx/releases/camera

支持扩展的设备

为了能使用 CameraX Extensions API，设备制造商需要实现 CameraX Vendor Extensions 接口。您可以在 CameraX 设备页面上找到支持 CameraX Extensions API 的部分设备列表。请注意，这不是一个详尽的列表。如果您的设备被列出，但可用性检查返回了 false，您可能需要将您的设备更新到制造商的最新 ROM 版本。

• CameraX Vendor Extensions 接口
  https://source.android.com/devices/camera/camerax-vendor-extensions

• CameraX 设备页面
  https://developer.android.google.cn/training/camerax/devices

除了支持扩展的设备列表外，从 Android 12 开始，您还可以通过检查 Android 属性ro.camerax.extensions.enabled来确定设备是否支持 CameraX Extensions。

移除旧版 Extensions API

2019 年 8 月发布的旧版 Extensions API 现已废弃。这个旧版的 Extensions API 提供了扩展器类，需要将扩展相关的配置应用到每个 Preview 和 ImageCapture 用例上。旧版的扩展器设计可能会导致开发人员忘记要在 Preview 或 ImageCapture 上启用扩展模式，并可能导致非预期的行为。

新的 CameraX Extensions 库在 1.0.0-alpha26 中引入。较新的 Extensions API 将扩展绑定从用例切换到目标相机，使用起来更加方便。请务必迁移以利用新的 Extensions API。

编辑：jq