CameraX Extensions API

CameraX предоставляет Extensions API для доступа к расширениям, которые производители устройств реализовали на различных устройствах Android. Список поддерживаемых режимов расширения приведен в разделе Расширения камеры.

Список устройств, поддерживающих расширения, приведен в разделе Поддерживаемые устройства.

Архитектура расширений

На изображении ниже показана архитектура расширений камеры.

Рисунок 1. Архитектура Camera Extensions

Приложение CameraX может использовать расширения через CameraX Extensions API. CameraX Extensions API управляет запросами доступных расширений, настраивает сеанс камеры с расширением и взаимодействует с OEM-библиотекой Camera Extensions. Это позволяет использовать в приложении такие функции, как ночная съемка, HDR, автоматический режим, боке и ретушь лица.

Как включить расширение для фотосъемки и предварительного просмотра изображений

Прежде чем использовать API расширений, получите экземпляр ExtensionsManager с помощью метода ExtensionsManager#getInstanceAsync(Context, CameraProvider). Это позволит вам запрашивать информацию о доступности расширения. Затем получите расширение с включенным CameraSelector. Режим расширения будет применяться к фотосъемке и предварительному просмотру при вызове метода bindToLifecycle() с включенным расширением CameraSelector.

Чтобы реализовать расширение для фотосъемки и предварительного просмотра, используйте следующий пример кода:

// import androidx.camera.extensions.ExtensionMode
// import androidx.camera.extensions.ExtensionsManager

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val lifecycleOwner = this

    val cameraProviderFuture = ProcessCameraProvider.getInstance(applicationContext)
    cameraProviderFuture.addListener({
        // Obtain an instance of a process camera provider.
        // The camera provider provides access to the set of cameras associated with the device.
        // The camera obtained from the provider will be bound to the activity lifecycle.
        val cameraProvider = cameraProviderFuture.get()

        val extensionsManagerFuture =
            ExtensionsManager.getInstanceAsync(applicationContext, cameraProvider)
        extensionsManagerFuture.addListener({
            // Obtain an instance of the extensions manager.
            // The extensions manager enables a camera to use extension capabilities available on
            // the device.
            val extensionsManager = extensionsManagerFuture.get()

            // Select the camera.
            val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA

            // Query if extension is available.
            // Not all devices will support extensions or might only support a subset of
            // extensions.
            if (extensionsManager.isExtensionAvailable(cameraSelector, ExtensionMode.NIGHT)) {
                // Unbind all use cases before enabling different extension modes.
                try {
                    cameraProvider.unbindAll()

                    // Retrieve a night extension enabled camera selector.
                    val nightCameraSelector =
                        extensionsManager.getExtensionEnabledCameraSelector(
                            cameraSelector,
                            ExtensionMode.NIGHT
                        )

                    // Bind image capture and preview use cases with the extension enabled camera
                    // selector.
                    val imageCapture = ImageCapture.Builder().build()
                    val preview = Preview.Builder().build()
                    // Connect the preview to receive the surface the camera outputs the frames
                    // to. This will allow displaying the camera frames in either a TextureView
                    // or SurfaceView. The SurfaceProvider can be obtained from the PreviewView.
                    preview.setSurfaceProvider(surfaceProvider)

                    // Returns an instance of the camera bound to the lifecycle.
                    // Use this camera object to control various operations with the camera.
                    // Example: flash, zoom, focus metering etc.
                    val camera = cameraProvider.bindToLifecycle(
                        lifecycleOwner,
                        nightCameraSelector,
                        imageCapture,
                        preview
                    )
                } catch (e: Exception) {
                    Log.e(TAG, "Use case binding failed", e)
                }
            }
        }, ContextCompat.getMainExecutor(this))
    }, ContextCompat.getMainExecutor(this))
}

Отключить расширение

Чтобы отключить расширения поставщика, отмените привязку всех вариантов использования и повторно привяжите варианты использования для фотосъемки и предварительного просмотра с помощью обычного селектора камеры. Например, переключитесь на основную камеру с помощью CameraSelector.DEFAULT_BACK_CAMERA.

Связанные запросы

API расширений CameraX реализован в библиотеке camera-extensions. Расширения зависят от основных модулей CameraX (core, camera2, lifecycle).

Яркий

dependencies {
  def camerax_version = "1.2.0-rc01"
  implementation "androidx.camera:camera-core:${camerax_version}"
  implementation "androidx.camera:camera-camera2:${camerax_version}"
  implementation "androidx.camera:camera-lifecycle:${camerax_version}"
  //the CameraX Extensions library
  implementation "androidx.camera:camera-extensions:${camerax_version}"
    ...
}

Kotlin

dependencies {
  val camerax_version = "1.2.0-rc01"
  implementation("androidx.camera:camera-core:${camerax_version}")
  implementation("androidx.camera:camera-camera2:${camerax_version}")
  implementation("androidx.camera:camera-lifecycle:${camerax_version}")
  // the CameraX Extensions library
  implementation("androidx.camera:camera-extensions:${camerax_version}")
    ...
}

Удаление устаревших API

В связи с выпуском нового Extensions API в 1.0.0-alpha26 поддержка устаревшего Extensions API, выпущенного в августе 2019 г., прекращена. Начиная с версии 1.0.0-alpha28, устаревший Extensions API удален из библиотеки. Приложения, использующие новый Extensions API, теперь должны получить объект CameraSelector с включенным расширением и использовать его для привязки вариантов использования.

Приложения, использующие устаревший Extensions API, должны перейти на новый Extensions API, чтобы обеспечить совместимость с будущими выпусками CameraX.

Дополнительные ресурсы

Чтобы узнать больше о CameraX, ознакомьтесь со следующими дополнительными ресурсами.

Практическая работа

  • Начало работы с CameraX

    • Пример кода

    Пример приложения с расширениями CameraX

    Другие справочные материалы

    Расширения CameraX от поставщиков

    Инструмент проверки расширений поставщиков CameraX