Interfejs API rozszerzeń CameraX

CameraX zapewnia interfejs API rozszerzeń umożliwiający dostęp do rozszerzeń, które producenci wdrożyli na różnych urządzeniach z Androidem. Listę obsługiwanych trybów rozszerzeń znajdziesz w artykule Rozszerzenia aparatu.

Listę urządzeń obsługujących rozszerzenia znajdziesz w sekcji Obsługiwane urządzenia.

Architektura rozszerzeń

Ilustracja poniżej przedstawia architekturę rozszerzeń aparatu.

Rysunek 1. Architektura rozszerzeń aparatu

Aplikacja CameraX może używać rozszerzeń przez interfejs CameraX Extensions API. CameraX Extensions API zarządza zapytaniami o dostępne rozszerzenia, konfigurując sesja kamery rozszerzenia i komunikacja z producentem rozszerzeń do aparatu. bibliotece. Dzięki temu aplikacja będzie mogła korzystać z funkcji takich jak Noc, HDR, Auto Bokeh lub retusz twarzy.

Włącz rozszerzenie do robienia zdjęć i wyświetlania ich podglądu

Przed użyciem interfejsu API rozszerzeń pobierz instancję ExtensionsManager za pomocą polecenia ExtensionsManager#getInstanceAsync(Context, CameraProvider) . Pozwoli Ci to wysyłać zapytania o dostępność rozszerzenia i informacjami o nich. Następnie pobierz rozszerzenie włączone CameraSelector. tryb rozszerzenia będzie stosowany do przechwytywania obrazu i podglądu, gdy: wywołanie funkcji bindToLifecycle(), z włączonym rozszerzeniem CameraSelector.

Uwaga: włączenie rozszerzeń na urządzeniach z systemem ImageCapture i Preview może ograniczyć liczbę aparatów, które możesz wybrać podczas używania ImageCapture i Preview jako do bindToLifecycle(). ExtensionsManager#getExtensionEnabledCameraSelector() zgłosi wyjątek jeśli nie zostaną znalezione żadne kamery, które obsługują rozszerzenie.

Aby wdrożyć rozszerzenie na potrzeby przechwytywania obrazu i wyświetlania podglądu, znajdziesz w tym przykładowym kodzie:

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

Wyłączanie rozszerzenia

Aby wyłączyć rozszerzenia dostawcy, usuń powiązanie wszystkich przypadków użycia i ponownie powiąż przechwytywanie obrazu i wyświetl podgląd przypadków użycia za pomocą zwykłego selektora aparatu. Na przykład ponownie utwórz powiązanie z elementem tylny aparat za pomocą funkcji CameraSelector.DEFAULT_BACK_CAMERA.

Zależności

Interfejs CameraX Extensions API jest zaimplementowany w bibliotece camera-extensions. Rozszerzenia zależą od podstawowych modułów CameraX (core, camera2, lifecycle).

Uwaga: aby zapewnić zgodność, musisz używać tych wersji rozszerzeń która znajduje się w tej samej bibliotece zwolnij pakiet jako odpowiedni podstawowych modułów kamery. Aby na przykład użyć pola camera-extensions:1.0.0-alpha28, musisz też dodać wersję 1.1.0-alpha28 dla camera-lifecycle, camera-core i camera-camera2, ponieważ wszystkie te moduły zostały udostępnione razem.

Odlotowe

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

Usunięcie starszej wersji interfejsu API

Po wprowadzeniu nowego interfejsu Extensions API w 1.0.0-alpha26 starsza wersja Interfejs Extensions API wprowadzony w sierpniu 2019 r. został wycofany. Od wersji 1.0.0-alpha28, starsza wersja interfejsu Extensions API została usunięta z bibliotece. Aplikacje korzystające z nowego interfejsu Extensions API muszą teraz uzyskiwać parametr z włączonym rozszerzeniem CameraSelector i wykorzystaj go do wiązania przypadków użycia.

W aplikacjach korzystających ze starszej wersji interfejsu Extensions API należy przejść na nową Interfejs Extensions API zapewnia w przyszłości zgodność z nadchodzącym Aparatem X wersji.

Dodatkowe materiały

Więcej informacji o aparacie AparatX znajdziesz w tych dodatkowych materiałach.

Ćwiczenia z programowania

Pierwsze kroki z AparatemX

Przykładowy kod

Przykładowa aplikacja rozszerzeń CameraX

Inne materiały

Rozszerzenia dla dostawców CameraX

Narzędzie do weryfikacji rozszerzeń dostawcy CameraX