配置选项

您可以使用配置接口类来配置每个 CameraX 用例，从而控制用例操作的不同方面。

例如，借助图片拍摄用例，您可以设置要使用的镜头、目标宽高比以及应如何完成线程。以下代码显示了一个示例：

Kotlin

    val config = ImageCaptureConfig.Builder()
        .setLensFacing(...)
        .setFlashMode(...)
        .setTargetAspectRatio(...)
        .build()
    

Java

    ImageCaptureConfig config =
        new ImageCaptureConfig.Builder()
            .setLensFacing(...)
            .setFlashMode(...)
            .setTargetAspectRatio(...)
            .build();
    

除了配置选项外，一些用例在创建后会公开 API 以动态更改设置。如需了解各个用例的专属配置，请参阅实现预览、分析图片和拍摄照片。

自动选择

CameraX 会自动提供专用于您的应用运行所在设备的功能。例如，如果您未指定分辨率或指定的分辨率不受支持，CameraX 会自动确定要使用的最佳分辨率。所有这一切都是在后台进行的，无需您编写设备专属代码。

CameraX 的目标是成功初始化相机会话。这意味着 CameraX 会根据设备功能降低分辨率和宽高比。降低的原因可能是：

• 设备不支持请求的分辨率。
• 设备存在兼容性问题，例如需要特定分辨率才能正常运行的旧设备。
• 在某些设备上，特定格式仅适用于特定宽高比。
• 对于 JPEG 或视频编码，设备首选“最近的 mod16”。如需了解详情，请参阅 SCALER_STREAM_CONFIGURATION_MAP。

尽管 CameraX 会创建并管理会话，但您应始终检查代码中用例输出上返回的图像大小，并进行相应调整。

旋转

默认情况下，在用例创建期间，相机旋转方向默认设置为与默认的显示屏旋转方向保持一致。在这种默认情况下，CameraX 会生成输出以允许应用轻松与您希望在预览中看到的画面保持一致。通过在配置用例对象时传入当前显示屏方向或在创建用例对象之后动态传入当前显示方向，您可以将旋转方向更改为自定义值以支持多显示屏设备。

您的应用可以使用配置构建器配置目标旋转方向。您的应用还可以通过使用用例 API 中的方法（例如 ImageAnalysis.setTargetRotation()）更新旋转设置，即使生命周期处于正在运行的状态也无妨。您可以在应用锁定为纵向模式时这样做，这样就无需对旋转方向重新进行任何配置，但是照片或分析用例需要知道设备当前的旋转方向。例如，用例可能需要知道旋转方向才能以正确的方向进行面部检测，或者照片设置为横向或纵向。

虽然在存储所拍摄图片的数据时并未将其旋转，Exif 数据也包含旋转信息，以便图库应用在保存后以正确的屏幕方向显示图片。

要以正确的方向显示预览数据，您可以使用 Preview.PreviewOutput() 的元数据输出为 GLSurfaceView 显示创建转换。

以下代码示例显示了如何通过配置 API 设置旋转：

Kotlin

    val previewConfig = PreviewConfig.Builder()
            .setTargetRotation(windowManager.defaultDisplay.rotation)
            .build()
    

Java

    PreviewConfig previewConfig =
      new PreviewConfig.Builder()
          .setTargetRotation(getWindowManager().getDefaultDisplay().getRotation())
          .build();
    

每个用例都会根据设定的旋转直接旋转图片数据或者向用户提供未旋转图片数据的旋转元数据。

• Preview：提供元数据输出以使用 Preview.PreviewOutput.getRotationDegrees() 为 GLSurfaceView 显示创建合适的转换。
• ImageAnalysis：提供元数据输出以便图片缓冲区坐标相对于显示坐标为已知。analyze() 方法提供了 rotationDegrees 参数来表示需要应用于图片分析数据以与取景器保持一致的旋转。
• ImageCapture：更改图片 Exif 元数据以为旋转设置添加注释。

相机分辨率

您可以选择允许 CameraX 根据设备功能、设备支持的硬件级别、用例和提供的宽高比组合设置图片分辨率。或者，您也可以在支持相应配置的用例中设置具有相应宽高比的特定目标分辨率。与目标宽高比匹配的分辨率的优先级高于特定的目标分辨率。

自动分辨率

CameraX 可以根据 CameraX.bindToLifecycle() 中指定的用例自动确定最佳分辨率设置。请尽可能在单个 CameraX.bindToLifecycle() 调用的单个会话中指定需要同时运行的所有用例。CameraX 会考虑设备支持的硬件级别以及设备专属变化（设备可能会超出或不满足可用的信息流配置），根据绑定的一组用例确定分辨率。这样做的目的是使应用可在各种设备上运行，同时最大限度地减少设备专属代码路径。

图片拍摄和图片分析用例的默认宽高比为 4:3。

用例具有一个可配置的宽高比，可允许应用根据界面设计指定所需的宽高比。CameraX 输出将会生成，以尽可能匹配设备支持的所请求宽高比。如果没有任何支持的完全匹配分辨率，则选择满足大多数条件的分辨率。因此，应用决定了相机应如何在应用中显示，CameraX 则会确定最佳相机分辨率设置以在不同的设备上满足这方面的要求。

例如，应用可能会执行以下任一操作：

• 将布局配置为以 4:3 的比例拍摄图片。
• 指定全屏布局。鉴于屏幕分辨率各不相同且考虑到系统界面栏，这一比例因设备而异。
• 指定方形布局。

CameraX 会自动选择内部 Camera2 界面分辨率。下表显示了这些分辨率：

用例	内部界面分辨率	输出数据分辨率
预览	宽高比：使目标与设置最相符的分辨率。	内部界面分辨率。提供元数据以允许 View 针对目标宽高比进行剪裁、缩放和旋转。
	默认分辨率：最高的预览分辨率，或与上述宽高比匹配的最高设备首选分辨率。
	最大分辨率：预览大小，指的是与设备的屏幕分辨率或 1080p (1920x1080) 匹配的最佳尺寸（以较低者为准）。
图片分析	宽高比：使目标与设置最相符的分辨率。	内部界面分辨率。
	默认分辨率：默认目标分辨率设置为 640x480。同时调整目标分辨率和相应的宽高比会导致支持的最佳分辨率低于 1080p。
	最大分辨率：CameraX 将其限制为 1080p。目标分辨率默认设置为 640x480；如果您希望分辨率大于 640x480，则必须使用 setTargetResolution 和 setTargetAspectRatio 从支持的分辨率中选择最接近的一个。
图片拍摄	宽高比：最适合设置的宽高比。	内部界面分辨率。
	默认分辨率：最高的可用分辨率，或与上述宽高比匹配的最高设备首选分辨率。
	最大分辨率：StreamConfigurationMap#getOutputSizes 中 JPEG 格式的相机设备的最大输出分辨率

指定分辨率

您可以在构建用例配置时使用 setTargetResolution(Size resolution) 方法设置特定的分辨率，如以下代码示例所示：

Kotlin

    val imageAnalysisConfig = ImageAnalysisConfig.Builder()
        .setTargetResolution(Size(1280, 720))
        .build()
    

Java

    ImageAnalysisConfig config =
      new ImageAnalysisConfig.Builder()
        .setTargetResolution(new Size(1280, 720))
        .build();
    

您可以根据指定的分辨率设置特定的目标宽高比。 目标宽高比会影响选择的分辨率。设置目标宽高比以匹配目标分辨率，从而获得选择的分辨率。最终的分辨率会考虑设备功能和其他附加用例。

如果无法满足所请求的确切分辨率和宽高比，则选择最接近且较高的边界分辨率；如果没有可用分辨率，则回退到 640x480。

CameraX 会根据请求应用最合适的分辨率。如果主要需求是满足宽高比要求，则仅指定 setTargetAspectRatio，CameraX 会根据设备确定合适的特定分辨率。如果应用的主要需求是指定分辨率以提高图片处理效率（例如根据设备处理能力处理较小或中等大小的图片），请使用 setTargetResolution(Size resolution)。

注意：如果使用 setTargetResolution，可能会收到宽高比与其他用例不匹配的缓冲区。如果宽高比必须匹配，请检查两个用例返回的缓冲区的尺寸，然后剪裁或缩放其中一个以与另一个匹配。

如果您的应用需要确切分辨率，请参阅 createCaptureSession 内的表格以确定每个硬件级别支持的最大分辨率。要检查当前设备支持的特定分辨率，请参阅 StreamConfigurationMap.getOutputSize(int)。

如果您的应用在 Android 10 上运行，您可以使用 isSessionConfigurationSupported 验证特定的 SessionConfiguration。

控制对焦

CameraControl API 提供“点按对焦”功能。您可以通过指定镜头朝向来获取 CameraControl：

Kotlin

    CameraX.getCameraControl(LensFacing lensFacing)
    

Java

    CameraX.getCameraControl(LensFacing lensFacing);
    

使用 MeteringPointFactory、MeteringPoint、MeteringMode 和 FocusMeteringAction 来运行点按对焦。

Kotlin

    val factory = SensorOrientedMeteringPointFactory(width, height)
    val point = factory.createPoint(x, y)
    val action = FocusMeteringAction.Builder.from(point,
        FocusMeteringAction.MeteringMode.AF_ONLY)
        .addPoint(point2, FocusMeteringAction.MeteringMode.AE_ONLY) // could have many
        .setAutoFocusCallback { }
        // auto calling cancelFocusAndMetering in 5 seconds
        .setAutoCancelDuration(5, TimeUnit.SECONDS)
        .build()
    

Java

    MeteringPointFactory factory = new SensorOrientedMeteringPointFactory(width, height);
    MeteringPoint point = factory.createPoint(x, y);
    FocusMeteringAction action = FocusMeteringAction.Builder.from(point,
                                     MeteringMode.AF_ONLY)
        .addPoint(point2, MeteringMode.AE_ONLY) // could have many
        .setAutoFocusCallback(new OnAutoFocusListener(){
            public void onFocusCompleted(boolean isSuccess) {
            }
        })
        // auto calling cancelFocusAndMetering in 5 seconds
        .setAutoCancelDuration(5, TimeUnit.SECONDS)
        .build();
    

其他资源

要详细了解 CameraX，请参阅下面列出的其他资源。

Codelab

CameraX 使用入门

代码示例

官方 CameraX 示例应用

开发者社区

Android CameraX 论坛