API Extensions de CameraX

CameraX fournit une API Extensions pour accéder aux extensions que les fabricants d'appareils ont implémentées sur divers appareils Android. Pour obtenir la liste des modes d'extension compatibles, consultez Extensions Camera.

Pour obtenir la liste des appareils compatibles avec les extensions, consultez Appareils compatibles.

Architecture des extensions

L'image suivante illustre l'architecture des extensions Camera.

Figure 1. Architecture des extensions Camera

Une application CameraX peut utiliser des extensions par le biais de l'API Extensions de CameraX. L'API Extensions de CameraX gère les requêtes liées aux extensions disponibles, la configuration d'une session de caméra d'extension et la communication avec la bibliothèque OEM d'extensions Camera. Votre application peut ainsi utiliser des fonctionnalités telles que Nuit, HDR, Auto, Bokeh ou Retouche du visage.

Activer une extension pour la capture d'image et l'aperçu

Avant d'utiliser l'API Extensions, récupérez une instance ExtensionsManager à l'aide de la méthode ExtensionsManager#getInstanceAsync(Context, CameraProvider). Cela vous permettra d'interroger les informations sur la disponibilité de l'extension. Ensuite, récupérez un CameraSelector activé pour l'extension. Le mode d'extension sera appliqué aux cas d'utilisation de capture d'image et d'aperçu lors de l'appel de la méthode bindToLifecycle() avec l'extension CameraSelector activée.

Remarque : L'activation des extensions sur ImageCapture et Preview peut limiter le nombre d'appareils photo que vous pouvez sélectionner lorsque vous utilisez ImageCapture et Preview en tant que paramètres de bindToLifecycle(). ExtensionsManager#getExtensionEnabledCameraSelector() génère une exception si aucun appareil photo n'est compatible avec l'extension.

Pour implémenter l'extension pour les cas d'utilisation de capture d'image et d'aperçu, reportez-vous à l'exemple de code suivant :

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

Désactiver l'extension

Pour désactiver les extensions du fournisseur, dissociez tous les cas d'utilisation, et associez à nouveau les cas d'utilisation de capture d'image et d'aperçu à un sélecteur d'appareil photo ordinaire. Par exemple, associez à nouveau la caméra arrière à l'aide de CameraSelector.DEFAULT_BACK_CAMERA.

Dépendances

L'API Extensions de CameraX est implémentée dans la bibliothèque camera-extensions. Les extensions dépendent des modules principaux de CameraX (core, camera2, lifecycle).

Remarque : Pour des raisons de compatibilité, vous devez utiliser la version de la bibliothèque d'extensions qui se trouve dans le même package de version que les principaux modules d'appareil photo correspondants. Par exemple, pour utiliser camera-extensions:1.0.0-alpha28, vous devez également inclure la version 1.1.0-alpha28 pour camera-lifecycle, camera-core et camera-camera2, car ces modules ont tous été publiés ensemble.

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

Suppression de l'ancienne API

Avec la publication de la nouvelle API Extensions dans la version 1.0.0-alpha26, l'ancienne API Extensions, publiée en août 2019, est maintenant obsolète. L'ancienne API Extensions a été supprimée de la bibliothèque à partir de la version 1.0.0-alpha28. Les applications qui utilisent la nouvelle API Extensions doivent maintenant obtenir un CameraSelector activé pour l'extension et l'utiliser pour lier les cas d'utilisation.

Les applications qui utilisent l'ancienne API Extensions doivent migrer vers la nouvelle API Extensions pour garantir la compatibilité avec les prochaines versions de CameraX.

Ressources supplémentaires

Pour en savoir plus sur CameraX, consultez les ressources supplémentaires suivantes.

Atelier de programmation

Premiers pas avec CameraX

Exemple de code

Application exemple pour les extensions CameraX

Autres références

Extensions du fournisseur CameraX

Outil de validation des extensions du fournisseur CameraX