CameraX Extensions API

CameraX には、デバイスのメーカーが各種 Android デバイスに実装した拡張機能にアクセスするための Extensions API が用意されています。サポートされている拡張機能モードの一覧については、カメラの拡張機能についての説明をご覧ください。

拡張機能をサポートするデバイスの一覧については、サポートされているデバイスについての説明をご覧ください。

拡張機能のアーキテクチャ

次の図は、カメラの拡張機能のアーキテクチャを示しています。

図 1. カメラの拡張機能のアーキテクチャ

CameraX アプリは、CameraX Extensions API を通じて拡張機能を使用できます。CameraX Extensions API は、利用可能な拡張機能の照会、拡張機能カメラ セッションの構成、Camera Extensions OEM ライブラリとの通信を管理します。これにより、アプリは夜景、HDR、オート、ボケ、顔写真加工などの機能を使用できます。

画像キャプチャとプレビューの拡張機能を有効にする

Extensions API を使用する前に、ExtensionsManager#getInstanceAsync(Context、CameraProvider)メソッドを使用して ExtensionsManager インスタンスを取得します。これにより、拡張機能の可用性情報をクエリできます。次に、拡張機能が有効になっている CameraSelector を取得します。CameraSelector 拡張機能を有効にして bindToLifecycle() メソッドを呼び出すとき、画像キャプチャとプレビューのユースケースに拡張機能モードが適用されます。

画像キャプチャとプレビューのユースケースの拡張機能を実装するには、次のコードサンプルをご覧ください。

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

拡張機能を無効にする

ベンダー拡張機能を無効にするには、すべてのユースケースをアンバインドし、画像キャプチャとプレビューのユースケースを通常のカメラセレクタで再バインドします。たとえば、CameraSelector.DEFAULT_BACK_CAMERA を使用して背面カメラに再バインドします。

依存関係

CameraX の Extensions API は、camera-extensions ライブラリに実装されています。拡張機能は CameraX コアモジュール(corecamera2lifecycle)に依存します。

Groovy

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

以前の API の削除

1.0.0-alpha26 での新しい Extensions API のリリースに伴い、2019 年 8 月にリリースされた以前の Extensions API のサポートは終了しました。バージョン 1.0.0-alpha28 以降、以前の Extensions API はライブラリから削除されています。新しい Extensions API を使用するアプリは、拡張機能が有効な CameraSelector を取得し、ユースケースをバインドする際に使用する必要があります。

以前の Extensions API を使用しているアプリは、今後の CameraX のリリースとの将来的な互換性を確保するために、新しい Extensions API に移行する必要があります。

参考情報

CameraX について詳しくは、以下の参考情報をご確認ください。

Codelab

  • CameraX のスタートガイド
  • コードサンプル

    CameraX 拡張機能のサンプルアプリ

    その他のリファレンス

    CameraX ベンダー拡張機能

    CameraX ベンダー拡張機能検証ツール