使用 PreviewView 来展现相机预览

显示相机预览内容是每一个相机类应用都会包含的功能，想要完美实现这个却并不是易事。缘由是，在某些特别极端状况下 camera2 API 的使用会变得很复杂，并且在不一样设备上的行为还会有所不一样。还好，Jetpack CameraX 库 的 PreviewView 能够帮助您解决这一问题。经过在各类 Android 设备上提供开发者友好、一致且稳定的 API，使得展现相机的预览变得再也不困难。

PreviewView 的介绍

PreviewView 是一个能够显示相机画面的自定义 View，它被构建的初衷即是下降开发者们在设置和处理相机所使用的预览画面 (preview surface) 的难度。

若是您须要在应用中提供展现相机画面的基本功能，使用 PreviewView 是最推荐的作法，它有如下几个优势:

• 使用简单 : PreviewView 是一个 View，它经过管理 Preview 用例所使用的 Surface 来实现将相机捕捉到的画面展现在界面布局中的所有功能；
• 代码轻量 : PreviewView 只专一于实现相机画面预览功能。它全部内部资源都致力于对相机预览画面的展现，以及在相机使用过程当中对预览画面 (preview surface) 进行管理。这样的关注点分离使得 PreviewView 的代码可以保持简洁；
• 支持全面 : PreviewView 解决了在屏幕上展现相机画面过程当中最难处理的部分，包括对画面宽高比、缩放和旋转的处理。不一样的设备会致使不一致的行为，包括设备、屏幕尺寸、摄像头硬件支持水平，还会须要适配诸如分屏模式、不一样锁定方向和可动态调节尺寸的展现窗口等显示模式，为了解决这些问题并在多种设备上提供无缝体验，PreviewView 还作了一些兼容性的处理。

PreviewView 的实现模式

PreviewView 是 FrameLayout 的子类，它会使用 SurfaceView 或者 TextureView 展现来自相机捕捉到的画面。一旦相机准备好，就会建立一个预览画面 (preview surface) 的实例，并在相机使用过程当中尽可能持有该实例，若是相机还在工做中却提早释放了所持有的预览画面 (preview surface) 实例，就会从新建立一个。

当涉及到诸如功耗和响应时间这些关键指标时，SurfaceView 的表现通常都比 TextureView 要好，这也是为何 PreviewView 会将 SurfaceView 做为默认实现模式的缘由。然而，一些设备 (主要是一些 旧版设备) 会在预览画面 (preview surface) 过早释放时出现闪退的状况。惋惜的是，使用 SurfaceView 时没法控制什么时候对画面 (surface) 进行释放，由于这是由 View 层级结构所控制的。所以在这些设备上，PreviewView 只能使用 TextureView 做为实现模式。另外在须要对相机预览界面进行旋转、改变透明度或加入动画的状况下，您也应该强制 PreviewView 使用 TextureView 做为实现模式。

您能够经过调用 PreviewView.setPreferredImplementationMode(ImplementationMode)) 并设置 ImplementationMode 参数为 SURFACE_VIEW 或 TEXTURE_VIEW 来更改 PreviewView 的实现模式。当首选模式设置为 SURFACE_VIEW 时，PreviewView 会尽量遵循您的设置 (使用 SurfaceView)；而当首选模式设置为 TEXTURE_VIEW 时，PreviewView 会确保一直使用 TEXTURE_VIEW 模式。

⚠️  在开始使用 PreviewView 以前，请务必经过调用 Preview.setSurfaceProvider(PreviewView.createSurfaceProvider())) 来设置您想要的实现模式。

下面介绍如何设置 PreviewView 的实现模式:

// 进行相机画面预览以前，设置想要的实现模式
previewView.preferredImplementationMode = ImplementationMode.SURFACE_VIEW

// 将 previewView 设置到 preview 用例中来开始进行相机画面预览
preview.setSurfaceProvider(previewView.createSurfaceProvider(cameraInfo))

PreviewView - Preview

PreviewView 经过处理建立 Preview 用例所须要的 SurfaceProvider，来启动一个预览画面的数据流。SurfaceProvider 会准备好须要提供给相机的 Surface，用来对预览画面的数据流进行展现，并负责在必要时从新建立 Surface。PreviewView.createSurfaceProvider(CameraInfo)) 接收一个 nullable 的 CameraInfo 实例。PreviewView 会结合所传入的 CameraInfo 参数，以及您所设定的实现模式和当前相机具有功能，来决定内部如何进行功能上的实现。若是您所传入的 CameraInfo 是一个 null，那 PreviewView 会使用 TextureView 做为实现模式，由于它没法肯定所选的相机若使用 SurfaceView 是否能够正常工做。

一旦您建立好了 Preview 用例和一些别的所须要的 实例 后，将它们绑定至 LifecycleOwner，使用所绑定的相机的 CameraInfo 来建立 SurfaceProvider，再将其绑定至 Preview 用例，调用 Preview.setSurfaceProvider(SurfaceProvider) 来启动预览画面数据流。

下面的例子展现了如何将 PreviewView 绑定至 Preview 来开启预览画面数据流:

// 建立 preview 用例
val preview = Preview.Builder().build()

// 将 preview 和其余须要的用例绑定到 lifecycle 中
val camera = cameraProvider.bindToLifecycle(lifecycleOwner, cameraSelector, preview, imageAnalysis, imageCapture)

// 使用所绑定相机的 cameraInfo 建立 surfaceProvider
val surfaceProvider = previewView.createSurfaceProvider(camera.cameraInfo)

// 将 surfaceProvider 绑定至 preview 用例来启动预览
preview.setSurfaceProvider(surfaceProvider)

PreviewView - 缩放 (scale) 类型

PreviewView 提供了一个 API，经过它可让您控制预览画面的样式是怎样的 (how) 和在父级视图中的位置 (where):

• how  决定将预览画面放置于 ( FIT ) 父级视图中仍是填充于 ( FILL ) 父级视图中；
• where  决定预览画面相对于父级视图来讲，是左上方对齐 ( START )，居中对齐 ( CENTER ) 仍是右下方对齐 ( END )。

"how" 和 "where" 所组合出来的结果，表明了 PreviewView 支持的缩放 (scale) 类型，包括 FIT_START、FIT_CENTER、FIT_END、FILL_START、FILL_CENTER and FILL_END。其中最经常使用的是 FIT_CENTER 和 FILL_CENTER，前者将预览界面在保证宽高比的前提下进行缩放而后居中，后者不会进行缩放，保证居中可是可能会致使画面被裁剪。

有两种方法能够设置缩放 (scale) 类型: 

• 经过在 XML 布局文件中设置 PreviewView 的 scaleType 属性来实现，如如下示例所示:

<androidx.camera.view.PreviewView
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:scaleType="fitEnd" />

• 在代码中经过调用 PreviewView.setScaleType(ScaleType)) 来实现，如如下示例所示:

previewView.setScaleType(ScaleType.FIT_CENTER)

想要获取到当前 PreviewView 所使用的缩放 (scale) 类型，调用 PreviewView.getScaleType()) 便可。

PreviewView - 摄像头控制操做

根据相机摄像头传感器的方向、设备的旋转方向、以及显示模式和预览比例，PreviewView 可能会对从相机接收到的预览帧进行相应地缩放、旋转和转换处理，以便在 UI 界面中能正确展现。这也是为何将 UI 坐标转换成摄像头传感器坐标是很重要的。在 CameraX 中，这种转换是由 MeteringPointFactory 完成的，它能够经过 PreviewView 提供的 API 进行建立: PreviewView.createMeteringPointFactory(cameraSelector))，其中 CameraSelector 参数表明所传入画面流数据的摄像头。

当您须要实现轻点对焦 (tap-to-focus) 功能的时候，PreviewView 的 MeteringPointFactor 轻易就可作到。尽管相机预览中默认启用了自动对焦 (须要摄像头支持)，但在 PreviewView 上点击时，您仍是能够控制对焦目标。MeteringPointFactory 会将对焦目标的坐标转换为摄像头传感器的坐标，而后再使用摄像头对该区域进行对焦。

下面的示例展现了如何使用 触摸监听器 (touch listener) 在 PreviewView 上实现轻点对焦功能:

fun onTouch(x: Float, y: Float) {
   // 建立 MeteringPoint，命名为 factory
    val factory = previewView.createMeteringPointFactory(cameraSelector)

   // 将 UI 界面的坐标转换为摄像头传感器的坐标

    val point = factory.createPoint(x, y)
    // 建立对焦须要用的 action 
    val action = FocusMeteringAction.Builder(point).build()
    // 执行所建立的对焦 action
    cameraControl.startFocusAndMetering(action)
}

另外一个在相机预览界面中经常使用的功能是捏拉缩放 (pinch-to-zoom)，它可让您经过在预览界面进行捏拉来实现画面的缩放操做。想要在 PreviewView 上实现它，在其之上添加一个 触摸监听器，并将其绑定到缩放手势监听器 (scale gesture listener) 上。这样就能够作到拦截捏拉手势，而后相应地更新摄像头的缩放比例。

下方的示例展现了如何在 PreviewView 上实现捏拉缩放 (pinch-to-zoom) 操做:

// 建立一个名为 listener 的回调函数，当手势事件发生时会调用这个回调函数

val listener = object : ScaleGestureDetector.SimpleOnScaleGestureListener() {

    override fun onScale(detector: ScaleGestureDetector): Boolean {

       // 获取当前的摄像头的缩放比例

        val currentZoomRatio: Float = cameraInfo.zoomRatio.value ?: 1F

        // 获取用户捏拉手势所更改的缩放比例

        val delta = detector.scaleFactor

        // 更新摄像头的缩放比例
        cameraControl.setZoomRatio(currentZoomRatio * delta)
        return true
    }
}

// 将 PreviewView 的触摸监听器绑定到缩放手势监听器上

val scaleGestureDetector = ScaleGestureDetector(context, listener)

// 将 PreviewView 的触摸事件传递给缩放手势监听器上

previewView.setOnTouchListener { _, event ->

    scaleGestureDetector.onTouchEvent(event)
    return@setOnTouchListener true
}

PreviewView - 如何进行测试

PreviewView 可在各类不一样的 Android 设备上提供一致的相机处理行为，这要归功于 CameraX 在 自动化测试实验室 中对 PreviewView 及其其余 API 上进行的投资。这些测试主要分为两个主要类别:

• 单元测试 能够结合当前的实现模式，缩放类型和 MeteringPointFactor 来验证 PreviewView 的行为。当出现父级视图的大小更改，或是展现的布局发生了变化，亦或是被绑定到 Window 上的状况时，单元测试还能够确保 PreviewView 在适当的时候可以正确地去调整预览画面；
• 集成测试 能够确保 PreviewView 集成到应用中，能够正常去显示或者中止显示来自相机的画面数据流。这些测试会验证 preview 在各类状况时的状态，包括在应用运行时进行屡次关闭而后从新打开，切换前置后置摄像头，以及应用的生命周期销毁后从新建立的状况。当前这些测试覆盖的主要范围是使用 TextureView 做为 PreviewView 的实现模式，由于使用 SurfaceView 以后想要捕获相机预览开始和结束时的信号会很是困难。

总结

综上所述:

• PreviewView 是一个自定义的 View，它能够方便地展现相机的预览画面；
• PreviewView 默认使用 SurfaceView 做为它预览画面 (preview surface) 的实现，可是在须要的时候会转而使用 TextureView；
• 将诸如 ImageCapture 和 ImageAnalysis 这样的用例绑定到 LifecycleOwner 上，建立一个 surfaceProvider，将其绑定到 Preview 用例来启动相机预览；
• 经过定义 PreviewView 的缩放类型来控制预览画面的展现方式；
• 经过给 PreviewView 建立 MeteringPointFactory 来实现对焦功能；
• 经过给 PreviewView 设置手势监听来实现捏拉缩放功能。

想了解更多关于 CameraX 的优秀功能吗？请查阅如下资料:

• Android 开发文档 | CameraX 概览
• Codelab | CameraX 使用指南
• 社区 | CameraX 线上开发者社区
• 示例代码 | 使用 CameraX 构建相机应用