CameraX Extensions API

Внимание! С 1 ноября 2026 года поддержка расширений CameraX будет прекращена на некоторых устройствах для приложений, использующих CameraX версии 1.5 или более ранней. Это изменение необходимо, чтобы улучшить производительность и надежность камеры. CameraX версии 1.6 и более поздних будет полностью поддерживать расширения CameraX. Чтобы приложение работало без перебоев, рекомендуем как можно скорее обновить его до CameraX версии 1.6 или выше.

В 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.

Примечание. Если включить расширения для ImageCapture и Preview, это может ограничить количество камер, которые можно выбрать, когда вы используете ImageCapture и Preview в качестве параметров для bindToLifecycle(). ExtensionsManager#getExtensionEnabledCameraSelector() выдаст исключение, если не будет найдено камер, поддерживающих расширение.

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

Kotlin

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

Java

import androidx.camera.extensions.ExtensionMode;
import androidx.camera.extensions.ExtensionsManager;

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    final LifecycleOwner lifecycleOwner = this;

    final ListenableFuture cameraProviderFuture =
            ProcessCameraProvider.getInstance(getApplicationContext());

    cameraProviderFuture.addListener(() -> {
      try {
          // 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.
          final ProcessCameraProvider cameraProvider = cameraProviderFuture.get();

          final ListenableFuture extensionsManagerFuture =
                  ExtensionsManager.getInstanceAsync(getApplicationContext(), cameraProvider);
          extensionsManagerFuture.addListener(() -> {
              // Obtain an instance of the extensions manager
              // The extensions manager enables a camera to use extension capabilities available
              // on the device.
              try {
                  final ExtensionsManager extensionsManager = extensionsManagerFuture.get();

                  // Select the camera
                  final CameraSelector 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.
                      cameraProvider.unbindAll();

                      // Retrieve extension enabled camera selector
                      final CameraSelector nightCameraSelector = extensionsManager
                              .getExtensionEnabledCameraSelector(cameraSelector, ExtensionMode.NIGHT);

                      // Bind image capture and preview use cases with the extension enabled camera
                      // selector.
                      final ImageCapture imageCapture = new ImageCapture.Builder().build();
                      final Preview preview = new 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);

                      cameraProvider.bindToLifecycle(
                              lifecycleOwner,
                              nightCameraSelector,
                              imageCapture,
                              preview
                      );
                  }
              } catch (ExecutionException | InterruptedException e) {
                  throw new RuntimeException(e);
              }
          }, ContextCompat.getMainExecutor(this));

      } catch (ExecutionException | InterruptedException e) {
          throw new RuntimeException(e);
      }

  }, ContextCompat.getMainExecutor(this));
}

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

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

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

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

Примечание. Чтобы обеспечить совместимость, используйте версию библиотеки расширений, которая находится в том же пакете выпуска, что и соответствующие основные модули камеры. Например, если вы используете camera-extensions:1.0.0-alpha28, то должны также включить версию 1.1.0-alpha28 для camera-lifecycle, camera-core и camera-camera2, поскольку все эти модули были выпущены вместе.

Яркий

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