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.

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.

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

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

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

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

Usunięcie starszej wersji interfejsu API

Po wprowadzeniu nowego interfejsu Extensions API w 1.0.0-alpha26 jego 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 powią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

Przykładowy kod

Przykładowa aplikacja rozszerzeń CameraX

Inne materiały

Rozszerzenia dla dostawców CameraX

Narzędzie do weryfikacji rozszerzeń dostawcy CameraX