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 im Hilfeartikel Unterstützte Geräte.

Erweiterungsarchitektur

Die folgende Abbildung zeigt die Architektur der Kameraerweiterungen.

</ph>

Eine CameraX-Anwendung kann Erweiterungen über die CameraX Extensions API verwenden. Die Die CameraX Extensions API verwaltet die Abfrage verfügbarer Erweiterungen und konfiguriert ein Erweiterung der Kamerasitzung und Kommunikation mit dem Kameraerweiterungs-OEM Bibliothek. Dadurch kann Ihre App Funktionen wie Nacht, HDR, Auto, Bokeh- oder Gesichtsretusche.

Erweiterung für Bildaufnahme und -vorschau aktivieren

Rufen Sie eine ExtensionsManager-Instanz ab, bevor Sie die Extensions API verwenden. mit ExtensionsManager#getInstanceAsync(Context, CameraProvider) . So können Sie die Verfügbarkeit der Erweiterung abfragen Informationen. Rufen Sie dann eine CameraSelector mit aktivierter Erweiterung ab. Die wird bei der Bilderfassung und der Vorschau in folgenden Fällen angewendet: bindToLifecycle() mit aktivierter Erweiterung CameraSelector an.

So implementieren Sie die Erweiterung für Anwendungsfälle zur Bilderfassung und -vorschau: erhalten Sie im folgenden Codebeispiel:

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

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

Heben Sie die Bindungen aller Anwendungsfälle auf und binden Sie die Bilderfassung noch einmal ein, um Anbietererweiterungen zu deaktivieren und eine Vorschau von Anwendungsfällen mit einer normalen Kameraauswahl anzeigen lassen. Beispiel: Erneute Bindung an den Rückkamera mit CameraSelector.DEFAULT_BACK_CAMERA.

Abhängigkeiten

Die CameraX Extensions API ist in der camera-extensions-Bibliothek implementiert. Die Erweiterungen hängen von den CameraX-Kernmodulen ab (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}"
    ...
}

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 alten API

Mit der Veröffentlichung der neuen Extensions API in 1.0.0-alpha26 wurde die alte Die im August 2019 veröffentlichte Extensions API wurde inzwischen eingestellt. Beginnend mit Version 1.0.0-alpha28, wurde die alte Extensions API aus dem Bibliothek. Anwendungen, die die neue Extensions API verwenden, müssen jetzt eine CameraSelector mit aktivierter Erweiterung und damit die Anwendungsfälle zu binden.

Anwendungen, die die alte Extensions API verwenden, sollten zur neuen Version migriert werden. Extensions API für zukünftige Kompatibilität mit der kommenden CameraX-Version Veröffentlichungen.

Weitere Informationen

Weitere Informationen zu CameraX finden Sie in den folgenden Ressourcen.

Codelab

Codebeispiel

Beispiel-App für KameraX-Erweiterungen

Sonstige Referenzen

CameraX-Anbietererweiterungen

Validierungstool für KameraX-Anbietererweiterungen