CameraX Uzantıları API'sı

CameraX, cihaz üreticilerinin çeşitli Android cihazlarda uyguladığı uzantılara erişmek için bir Extensions API sağlar. Desteklenen uzantı modlarının listesi için Kamera uzantıları başlıklı makaleyi inceleyin.

Uzantıları destekleyen cihazların listesi için Desteklenen cihazlar bölümüne bakın.

Uzantı mimarisi

Aşağıdaki resimde kamera uzantıları mimarisi gösterilmektedir.

Şekil 1. Kamera Uzantıları mimarisi

CameraX uygulamaları, CameraX Extensions API aracılığıyla uzantıları kullanabilir. CameraX Extensions API, kullanılabilir uzantılar için sorgu göndermeyi, uzantı kamera oturumu yapılandırmayı ve Camera Extensions OEM kitaplığıyla iletişimi yönetir. Bu sayede uygulamanız Gece, HDR, Otomatik, Bokeh veya Yüz Rötuşu gibi özellikleri kullanabilir.

Görüntü yakalama ve önizleme için bir uzantıyı etkinleştirme

Extensions API'yi kullanmadan önce ExtensionsManager#getInstanceAsync(Context, CameraProvider) yöntemini kullanarak bir ExtensionsManager örneği alın. Bu sayede uzantı müsaitlik durumu bilgilerini sorgulayabilirsiniz. Ardından, etkinleştirilmiş bir uzantı CameraSelector alın. CameraSelector uzantısı etkinleştirilmişken bindToLifecycle() yöntemi çağrıldığında uzantı modu, görüntü yakalama ve önizleme kullanım alanlarında uygulanır.

Görüntü yakalama ve önizleme kullanım alanları için uzantıyı uygulamak üzere aşağıdaki kod örneğine bakın:

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

Uzantıyı devre dışı bırakma

Tedarikçi uzantılarını devre dışı bırakmak için tüm kullanım alanlarının bağlantısını kaldırın ve görüntü yakalama ile önizleme kullanım alanlarını normal bir kamera seçiciyle yeniden bağlayın. Örneğin, CameraSelector.DEFAULT_BACK_CAMERA kullanarak arka kameraya yeniden bağlayın.

Bağımlılıklar

CameraX Extensions API, camera-extensions kitaplığında uygulanır. Uzantılar, CameraX çekirdek modüllerine (core, camera2, lifecycle) bağlıdır.

Modern

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

Eski API'lerin kaldırılması

1.0.0-alpha26 sürümünde kullanıma sunulan yeni Extensions API ile Ağustos 2019'da kullanıma sunulan eski Extensions API'nin desteği sonlandırıldı. 1.0.0-alpha28 sürümünden itibaren eski Uzantılar API'si kitaplıktan kaldırıldı. Yeni Extensions API'yi kullanan uygulamaların artık bir CameraSelector uzantı etkinleştirme anahtarı edinmesi ve kullanım alanlarını bağlamak için bu anahtarı kullanması gerekir.

Eski Uzantılar API'sini kullanan uygulamalar, gelecekteki CameraX sürümleriyle uyumluluğu sağlamak için yeni Uzantılar API'ye geçmelidir.

Ek kaynaklar

CameraX hakkında daha fazla bilgi edinmek için aşağıdaki ek kaynaklara göz atın.

Codelab

  • CameraX'i Kullanmaya Başlama
  • Kod örneği

    CameraX Uzantıları Örnek Uygulaması

    Diğer referanslar

    CameraX Vendor Extensions

    CameraX Vendor Extensions Validation Tool