CameraX 提供了一个扩展 API，用于访问设备制造商在各种 Android 设备上实施的扩展。有关支持的扩展模式列表，请参阅相机扩展。
有关支持扩展的设备列表，请参阅支持的设备。
扩展架构
以下图片显示了相机扩展架构。
CameraX 应用可以通过 CameraX 扩展 API 使用扩展。CameraX 扩展 API 管理查询可用扩展、配置扩展相机会话以及与相机扩展 OEM 库通信。这使您的应用可以使用夜间、HDR、自动、散景或面部美化等功能。
启用扩展以进行图像捕获和预览
在使用扩展 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 扩展 API 在 camera-extensions 库中实现。扩展依赖于 CameraX 核心模块（core、camera2、lifecycle）。
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 中发布的新的扩展 API，2019 年 8 月发布的旧版扩展 API 现已弃用。从版本 1.0.0-alpha28 开始，旧版扩展 API 已从库中移除。使用新的扩展 API 的应用程序现在必须获取一个启用扩展的 CameraSelector 并使用它来绑定用例。
使用旧版扩展 API 的应用程序应迁移到新的扩展 API 以确保与即将发布的 CameraX 版本的未来兼容性。
其他资源
要详细了解 CameraX，请参考以下其他资源。
Codelab