CameraX Extensions API

CameraX bietet eine Extensions API für den Zugriff auf Erweiterungen, die Gerätehersteller auf verschiedenen Android-Geräten implementiert haben. Eine Liste der unterstützten Erweiterungsmodi finden Sie unter Kameraerweiterungen.

Eine Liste der Geräte, die Erweiterungen unterstützen, finden Sie unter Unterstützte Geräte.

Architektur von Erweiterungen

Die folgende Abbildung zeigt die Architektur der Kameraerweiterungen.

Abbildung 1. Architektur der Kameraerweiterungen

Eine CameraX-Anwendung kann Erweiterungen über die CameraX Extensions API verwenden. Die CameraX Extensions API verwaltet die Abfrage nach verfügbaren Erweiterungen, die Konfiguration einer Kameraerweiterungssitzung und die Kommunikation mit der OEM-Bibliothek für Kameraerweiterungen. So kann Ihre Anwendung Funktionen wie „Nacht“, „HDR“, „Auto“, „Bokeh“ oder „Gesichtsretusche“ nutzen.

Erweiterung für die Bildaufnahme und ‑vorschau aktivieren

Bevor Sie die Extensions API verwenden, rufen Sie eine ExtensionsManager Instanz mit der Methode ExtensionsManager#getInstanceAsync(Context, CameraProvider) ab. So können Sie Informationen zur Verfügbarkeit von Erweiterungen abfragen. Rufen Sie dann einen CameraSelector ab, bei dem die Erweiterung aktiviert ist. Der Erweiterungsmodus wird auf die Anwendungsfälle für die Bildaufnahme und ‑vorschau angewendet, wenn Sie die bindToLifecycle() Methode mit der CameraSelector Erweiterung aufrufen.

Informationen zum Implementieren der Erweiterung für die Anwendungsfälle für die Bildaufnahme und ‑vorschau finden Sie im folgenden Codebeispiel:

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

Erweiterung deaktivieren

Wenn Sie Anbietererweiterungen deaktivieren möchten, heben Sie die Bindung aller Anwendungsfälle auf und binden Sie die Anwendungsfälle für die Bildaufnahme und ‑vorschau mit einem normalen Kameraauswähler neu. Binden Sie beispielsweise mit CameraSelector.DEFAULT_BACK_CAMERA neu an die Rückkamera.

Abhängigkeiten

Die CameraX Extensions API ist in der Bibliothek camera-extensions implementiert. Die Erweiterungen sind von den CameraX-Kernmodulen (core, camera2, lifecycle) abhängig.

Groovy

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

Entfernung der Legacy-API

Mit der neuen Extensions API, die in 1.0.0-alpha26 veröffentlicht wurde, ist die Legacy Extensions API, die im August 2019 veröffentlicht wurde, jetzt veraltet. Ab Version 1.0.0-alpha28 wurde die Legacy Extensions API aus der Bibliothek entfernt. Anwendungen, die die neue Extensions API verwenden, müssen jetzt einen mit aktivierter Erweiterung CameraSelector abrufen und damit die Anwendungsfälle binden.

Anwendungen, die die Legacy Extensions API verwenden, sollten zur neuen Extensions API migrieren, um die zukünftige Kompatibilität mit kommenden CameraX-Releases zu gewährleisten.

Zusätzliche Ressourcen

Weitere Informationen zu CameraX finden Sie in den folgenden zusätzlichen Ressourcen.

Codelab

  • Erste Schritte mit CameraX
  • Codebeispiel

    CameraX-Erweiterungen – Beispiel-App

    Sonstige Referenzen

    CameraX-Anbietererweiterungen

    Validierungstool für CameraX-Anbietererweiterungen