API CameraX Extensions

CameraX fornisce un'API Extensions per accedere alle estensioni che i produttori di dispositivi hanno implementato su vari dispositivi Android. Per un elenco delle modalità di estensione supportate, consulta Estensioni della fotocamera.

Per un elenco dei dispositivi che supportano le estensioni, vedi Dispositivi supportati.

Architettura delle estensioni

L'immagine seguente mostra l'architettura delle estensioni della fotocamera.

Figura 1. Architettura delle estensioni della fotocamera

Un'applicazione CameraX può utilizzare le estensioni tramite l'API CameraX Extensions. La L'API CameraX Extensions gestisce le query per le estensioni disponibili, configurando un estensione della sessione della fotocamera e comunicare con l'OEM delle estensioni della fotocamera libreria. L'applicazione può usare funzionalità quali Notte, HDR, Auto Bokeh o Ritocco viso.

Attiva un'estensione per l'acquisizione e l'anteprima delle immagini

Prima di utilizzare l'API Extensions, recupera un'istanza ExtensionsManager utilizzando extensionsManager#getInstanceAsync(Context, CameraProvider) . In questo modo potrai eseguire query sulla disponibilità delle estensioni informazioni. Quindi recupera un'estensione attivata CameraSelector. La verrà applicata ai casi d'uso di acquisizione e anteprima delle immagini quando la chiamata a bindToLifecycle() con l'estensione CameraSelector attivata.

Nota: l'attivazione delle estensioni su ImageCapture e Preview potrebbe limitare il numero di videocamere che puoi selezionare quando utilizzi ImageCapture e Preview come parametri in bindToLifecycle(). ExtensionsManager#getExtensionEnabledCameraSelector() genererà un'eccezione se non vengono trovate fotocamere che supportano l'estensione.

Per implementare l'estensione per i casi d'uso relativi all'acquisizione e all'anteprima delle immagini, fai riferimento al seguente esempio di codice:

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

Disattiva l'estensione

Per disattivare le estensioni del fornitore, svincola tutti i casi d'uso e ricollega l'acquisizione dell'immagine e visualizzare l'anteprima dei casi d'uso con un normale selettore della fotocamera. Ad esempio, associa nuovamente al fotocamera posteriore utilizzando CameraSelector.DEFAULT_BACK_CAMERA.

Dipendenze

L'API CameraX Extensions è implementata nella libreria camera-extensions. Le estensioni dipendono dai moduli principali di CameraX (core, camera2, lifecycle).

Nota: per garantire la compatibilità, devi utilizzare la versione delle estensioni che si trova nello stesso pacchetto di release come il moduli principali della fotocamera. Ad esempio, per utilizzare camera-extensions:1.0.0-alpha28, devi includere anche la versione 1.1.0-alpha28 per camera-lifecycle, camera-core e camera-camera2, poiché questi moduli sono stati rilasciati tutti in sinergia.

Alla moda

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

Rimozione dell'API precedente

Con la nuova API Extensions rilasciata nel mese di 1.0.0-alpha26, la versione L'API Extensions rilasciata ad agosto 2019 è stata ritirata. A partire da versione 1.0.0-alpha28, l'API Extensions per la versione precedente è stata rimossa dal libreria. Le applicazioni che utilizzano la nuova API Extensions devono ora acquisire con estensione attivata CameraSelector e utilizzarla per associare i casi d'uso.

Le applicazioni che utilizzano l'API Extensions legacy devono essere migrate alla nuova l'API Extensions per garantire la compatibilità futura con CameraX in arrivo nuove versioni.

Risorse aggiuntive

Per saperne di più su CameraX, consulta le risorse aggiuntive che seguono.

Codelab

Iniziare a usare CameraX

Esempio di codice

App di esempio delle estensioni di CameraX

Altri riferimenti

Estensioni dei fornitori di CameraX

Strumento di convalida delle estensioni del fornitore di CameraX