CameraX Extensions API

CameraX یک Extensions API برای دسترسی به افزونه‌هایی ارائه می‌دهد که سازندگان دستگاه در دستگاه‌های مختلف Android پیاده‌سازی کرده‌اند. برای مشاهده فهرست حالت‌های افزونه پشتیبانی‌شده، به افزونه‌های دوربین مراجعه کنید.

برای مشاهده فهرست دستگاه‌هایی که از افزونه‌ها پشتیبانی می‌کنند، به دستگاه‌های پشتیبانی‌شده مراجعه کنید.

معماری افزونه‌ها

تصویر زیر معماری افزونه‌های دوربین را نشان می‌دهد.

شکل ۱. معماری «افزونه‌های دوربین»

برنامه CameraX می‌تواند ازطریق CameraX Extensions API از افزونه‌ها استفاده کند. CameraX Extensions API جستجوی افزونه‌های دردسترس، پیکربندی جلسه دوربین افزونه، و برقراری ارتباط با کتابخانه Camera Extensions OEM را مدیریت می‌کند. این کار به برنامه شما اجازه می‌دهد از قابلیت‌هایی مانند «حالت شب»، HDR، «خودکار»، «بوکه»، یا «رتوش چهره» استفاده کند.

فعال کردن افزونه برای ضبط و پیش‌نمایش تصویر

قبل‌از استفاده از API افزونه‌ها، بااستفاده از روش ExtensionsManager#getInstanceAsync(Context, CameraProvider)، یک نمونه ExtensionsManager را بازیابی کنید. این کار به شما امکان می‌دهد اطلاعات دردسترس بودن افزونه را پُرسمان کنید. سپس افزونه فعال‌شده CameraSelector را بازیابی کنید. وقتی روش bindToLifecycle() با افزونه CameraSelector فعال‌شده فراخوانی شود، حالت افزونه بر موارد استفاده ضبط تصویر و پیش‌نمایش اعمال خواهد شد.

برای پیاده‌سازی افزونه برای موارد استفاده ضبط و پیش‌نمایش تصویر، به نمونه کد زیر مراجعه کنید:

کاتلین

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

غیرفعال کردن افزونه

برای غیرفعال کردن افزونه‌های فروشنده، همه موارد استفاده را لغو اتصال کنید و موارد استفاده ضبط تصویر و پیش‌نمایش را با انتخابگر دوربین معمولی دوباره متصل کنید. برای مثال، بااستفاده از CameraSelector.DEFAULT_BACK_CAMERA، دوباره به دوربین پشت متصل شوید.

وابستگی‌ها

CameraX Extensions API در کتابخانه camera-extensions پیاده‌سازی شده است. افزونه‌ها به ماژول‌های اصلی 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}")
    ...
}

برداشتن میانای برنامه‌سازی کاربردی قدیمی

با انتشار Extensions API جدید در 1.0.0-alpha26، Extensions API قدیمی که در اوت ۲۰۱۹ منتشر شده بود اکنون منسوخ شده است. از نسخه 1.0.0-alpha28، میانای برنامه‌سازی کاربردی «افزونه‌های» قدیمی از کتابخانه برداشته شده است. برنامه‌هایی که از Extensions API جدید استفاده می‌کنند اکنون باید CameraSelector فعال‌شده با افزونه را دریافت کنند و از آن برای مقید کردن موارد استفاده استفاده کنند.

برنامه‌هایی که از Extensions API قدیمی استفاده می‌کنند باید به Extensions API جدید منتقل شوند تا از سازگاری آینده با نسخه‌های آتی CameraX اطمینان حاصل شود.

منابع بیشتر

برای کسب اطلاعات بیشتر درباره CameraX، به منابع اضافی زیر مراجعه کنید.

Codelab

  • شروع به کار کردن با CameraX
  • نمونه کد

    CameraX Extensions Sample App

    منابع دیگر

    افزونه‌های فروشنده CameraX

    CameraX Vendor Extensions Validation Tool