屏幕闪光，也称为前置闪光或自拍闪光，利用手机屏幕亮度在弱光条件下使用前置摄像头拍摄图像时照亮拍摄对象。它在许多原生相机应用程序和社交媒体应用程序中都可用。由于大多数人在构图自拍时将手机拿得足够近，因此这种方法很有效。
但是，开发人员很难正确实现此功能并始终保持跨设备良好的捕获质量。本指南展示了如何使用 Camera2（低级 Android 相机框架 API）正确实现此功能。
常规工作流程
要正确实现此功能，两个关键因素是使用预捕获测光序列（自动曝光预捕获）和操作的时机。常规工作流程如 图 1 所示。
当需要使用屏幕闪光功能拍摄图像时，将使用以下步骤。
- 应用屏幕闪光所需的 UI 更改，这可以为使用设备屏幕拍摄照片提供足够的光线。对于一般用例，Google 建议使用以下 UI 更改，如我们在测试中所用。
- 应用程序屏幕覆盖白色颜色叠加层。
- 屏幕亮度最大化。
- 如果支持，将自动曝光 (AE) 模式设置为
CONTROL_AE_MODE_ON_EXTERNAL_FLASH。 - 使用
CONTROL_AE_PRECAPTURE_TRIGGER触发预捕获测光序列。 等待自动曝光 (AE) 和自动白平衡 (AWB) 收敛。
收敛后，使用应用程序的常规照片捕获流程。
将捕获请求发送到框架。
等待接收捕获结果。
如果设置了
CONTROL_AE_MODE_ON_EXTERNAL_FLASH，请重置 AE 模式。清除屏幕闪光的 UI 更改。
Camera2 示例代码
用白色叠加层覆盖应用程序屏幕
在应用程序的布局 XML 文件中添加一个 View。该视图具有足够的提升高度，可以在屏幕闪光捕获期间位于所有其他 UI 元素之上。默认情况下，它保持不可见，只有在应用屏幕闪光 UI 更改时才会可见。
在以下代码示例中，白色 (#FFFFFF) 用作视图的示例。应用程序可以根据其要求选择颜色，或向用户提供多种颜色。
<View
android:id="@+id/white_color_overlay"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:background="#FFFFFF"
android:visibility="invisible"
android:elevation="8dp" />
最大化屏幕亮度
在 Android 应用程序中，有许多方法可以更改屏幕亮度。一种直接的方法是更改 screenBrightness Activity Window 引用中的 WindowManager 参数。
Kotlin
private var previousBrightness: Float = -1.0f
private fun maximizeScreenBrightness() {
activity?.window?.let { window ->
window.attributes?.apply {
previousBrightness = screenBrightness
screenBrightness = 1f
window.attributes = this
}
}
}
private fun restoreScreenBrightness() {
activity?.window?.let { window ->
window.attributes?.apply {
screenBrightness = previousBrightness
window.attributes = this
}
}
}
Java
private float mPreviousBrightness = -1.0f;
private void maximizeScreenBrightness() {
if (getActivity() == null || getActivity().getWindow() == null) {
return;
}
Window window = getActivity().getWindow();
WindowManager.LayoutParams attributes = window.getAttributes();
mPreviousBrightness = attributes.screenBrightness;
attributes.screenBrightness = 1f;
window.setAttributes(attributes);
}
private void restoreScreenBrightness() {
if (getActivity() == null || getActivity().getWindow() == null) {
return;
}
Window window = getActivity().getWindow();
WindowManager.LayoutParams attributes = window.getAttributes();
attributes.screenBrightness = mPreviousBrightness;
window.setAttributes(attributes);
}
将 AE 模式设置为 CONTROL_AE_MODE_ON_EXTERNAL_FLASH
CONTROL_AE_MODE_ON_EXTERNAL_FLASH 可用于 API 级别 28 或更高版本。但是，并非所有设备都提供此 AE 模式，因此请检查 AE 模式是否可用，并相应地设置值。要检查可用性，请使用 CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES。
Kotlin
private val characteristics: CameraCharacteristics by lazy {
cameraManager.getCameraCharacteristics(cameraId)
}
@RequiresApi(Build.VERSION_CODES.P)
private fun isExternalFlashAeModeAvailable() =
characteristics.get(CameraCharacteristics.CONTROL_AE_AVAILABLE_MODES)
?.contains(CaptureRequest.CONTROL_AE_MODE_ON_EXTERNAL_FLASH) ?: false
Java
try {
mCharacteristics = mCameraManager.getCameraCharacteristics(mCameraId);
} catch (CameraAccessException e) {
e.printStackTrace();
}
@RequiresApi(Build.VERSION_CODES.P)
private boolean isExternalFlashAeModeAvailable() {
int[] availableAeModes = mCharacteristics.get(CameraCharacteristics.CONTROL_AE_AVAILABLE_MODES);
for (int aeMode : availableAeModes) {
if (aeMode == CaptureRequest.CONTROL_AE_MODE_ON_EXTERNAL_FLASH) {
return true;
}
}
return false;
}
如果应用程序设置了重复捕获请求（对于预览是必需的），则需要将 AE 模式设置为重复请求。否则，它可能会被下次重复捕获中的默认 AE 模式或其他用户设置的 AE 模式覆盖。如果发生这种情况，相机可能没有足够的时间来完成针对外部闪光灯 AE 模式通常执行的所有操作。
为了帮助确保相机完全处理 AE 模式更新请求，请检查重复捕获回调中的捕获结果，并在结果中等待 AE 模式更新。
可以等待 AE 模式更新的捕获回调
以下代码片段展示了如何实现这一点。
Kotlin
private val repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {
private var targetAeMode: Int? = null
private var aeModeUpdateDeferred: CompletableDeferred? = null
suspend fun awaitAeModeUpdate(targetAeMode: Int) {
this.targetAeMode = targetAeMode
aeModeUpdateDeferred = CompletableDeferred()
// Makes the current coroutine wait until aeModeUpdateDeferred is completed. It is
// completed once targetAeMode is found in the following capture callbacks
aeModeUpdateDeferred?.await()
}
private fun process(result: CaptureResult) {
// Checks if AE mode is updated and completes any awaiting Deferred
aeModeUpdateDeferred?.let {
val aeMode = result[CaptureResult.CONTROL_AE_MODE]
if (aeMode == targetAeMode) {
it.complete(Unit)
}
}
}
override fun onCaptureCompleted(
session: CameraCaptureSession,
request: CaptureRequest,
result: TotalCaptureResult
) {
super.onCaptureCompleted(session, request, result)
process(result)
}
}
Java
static class AwaitingCaptureCallback extends CameraCaptureSession.CaptureCallback {
private int mTargetAeMode;
private CountDownLatch mAeModeUpdateLatch = null;
public void awaitAeModeUpdate(int targetAeMode) {
mTargetAeMode = targetAeMode;
mAeModeUpdateLatch = new CountDownLatch(1);
// Makes the current thread wait until mAeModeUpdateLatch is released, it will be
// released once targetAeMode is found in the capture callbacks below
try {
mAeModeUpdateLatch.await();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
private void process(CaptureResult result) {
// Checks if AE mode is updated and decrements the count of any awaiting latch
if (mAeModeUpdateLatch != null) {
int aeMode = result.get(CaptureResult.CONTROL_AE_MODE);
if (aeMode == mTargetAeMode) {
mAeModeUpdateLatch.countDown();
}
}
}
@Override
public void onCaptureCompleted(@NonNull CameraCaptureSession session,
@NonNull CaptureRequest request,
@NonNull TotalCaptureResult result) {
super.onCaptureCompleted(session, request, result);
process(result);
}
}
private final AwaitingCaptureCallback mRepeatingCaptureCallback = new AwaitingCaptureCallback();
设置重复请求以启用或禁用 AE 模式
有了捕获回调，以下代码示例展示了如何设置重复请求。
Kotlin
/** [HandlerThread] where all camera operations run */
private val cameraThread = HandlerThread("CameraThread").apply { start() }
/** [Handler] corresponding to [cameraThread] */
private val cameraHandler = Handler(cameraThread.looper)
private suspend fun enableExternalFlashAeMode() {
if (Build.VERSION.SDK_INT >= 28 && isExternalFlashAeModeAvailable()) {
session.setRepeatingRequest(
camera.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW).apply {
addTarget(previewSurface)
set(
CaptureRequest.CONTROL_AE_MODE,
CaptureRequest.CONTROL_AE_MODE_ON_EXTERNAL_FLASH
)
}.build(), repeatingCaptureCallback, cameraHandler
)
// Wait for the request to be processed by camera
repeatingCaptureCallback.awaitAeModeUpdate(CaptureRequest.CONTROL_AE_MODE_ON_EXTERNAL_FLASH)
}
}
private fun disableExternalFlashAeMode() {
if (Build.VERSION.SDK_INT >= 28 && isExternalFlashAeModeAvailable()) {
session.setRepeatingRequest(
camera.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW).apply {
addTarget(previewSurface)
}.build(), repeatingCaptureCallback, cameraHandler
)
}
}
Java
private void setupCameraThread() {
// HandlerThread where all camera operations run
HandlerThread cameraThread = new HandlerThread("CameraThread");
cameraThread.start();
// Handler corresponding to cameraThread
mCameraHandler = new Handler(cameraThread.getLooper());
}
private void enableExternalFlashAeMode() {
if (Build.VERSION.SDK_INT >= 28 && isExternalFlashAeModeAvailable()) {
try {
CaptureRequest.Builder requestBuilder = mCamera.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);
requestBuilder.addTarget(mPreviewSurface);
requestBuilder.set(CaptureRequest.CONTROL_AE_MODE, CaptureRequest.CONTROL_AE_MODE_ON_EXTERNAL_FLASH);
mSession.setRepeatingRequest(requestBuilder.build(), mRepeatingCaptureCallback, mCameraHandler);
} catch (CameraAccessException e) {
e.printStackTrace();
}
// Wait for the request to be processed by camera
mRepeatingCaptureCallback.awaitAeModeUpdate(CaptureRequest.CONTROL_AE_MODE_ON_EXTERNAL_FLASH);
}
}
private void disableExternalFlashAeMode() {
if (Build.VERSION.SDK_INT >= 28 && isExternalFlashAeModeAvailable()) {
try {
CaptureRequest.Builder requestBuilder = mCamera.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);
requestBuilder.addTarget(mPreviewSurface);
mSession.setRepeatingRequest(requestBuilder.build(), mRepeatingCaptureCallback, mCameraHandler);
} catch (CameraAccessException e) {
e.printStackTrace();
}
}
}
触发预捕获序列
要触发预捕获测光序列，您可以提交一个 CaptureRequest，并将 CONTROL_AE_PRECAPTURE_TRIGGER_START 值设置为该请求。您需要等待该请求完成处理，然后等待 AE 和 AWB 收敛。
虽然预捕获使用单个捕获请求触发，但等待 AE 和 AWB 收敛确实需要更大的复杂性。您可以使用设置为重复请求的捕获回调来跟踪 AE 状态 和 AWB 状态。
更新相同的重复回调可以让您拥有代码简洁性。应用程序通常需要预览，他们会在设置相机时为其设置重复请求。因此，您可以在初始化时将重复捕获回调设置为该初始重复请求，然后重新用于结果检查和等待目的。
捕获回调代码更新以等待收敛
要更新重复捕获回调，请使用以下代码片段。
Kotlin
private val repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {
private var targetAeMode: Int? = null
private var aeModeUpdateDeferred: CompletableDeferred? = null
private var convergenceDeferred: CompletableDeferred? = null
suspend fun awaitAeModeUpdate(targetAeMode: Int) {
this.targetAeMode = targetAeMode
aeModeUpdateDeferred = CompletableDeferred()
// Makes the current coroutine wait until aeModeUpdateDeferred is completed. It is
// completed once targetAeMode is found in the following capture callbacks
aeModeUpdateDeferred?.await()
}
suspend fun awaitAeAwbConvergence() {
convergenceDeferred = CompletableDeferred()
// Makes the current coroutine wait until convergenceDeferred is completed, it will be
// completed once both AE & AWB are reported as converged in the capture callbacks below
convergenceDeferred?.await()
}
private fun process(result: CaptureResult) {
// Checks if AE mode is updated and completes any awaiting Deferred
aeModeUpdateDeferred?.let {
val aeMode = result[CaptureResult.CONTROL_AE_MODE]
if (aeMode == targetAeMode) {
it.complete(Unit)
}
}
// Checks for convergence and completes any awaiting Deferred
convergenceDeferred?.let {
val aeState = result[CaptureResult.CONTROL_AE_STATE]
val awbState = result[CaptureResult.CONTROL_AWB_STATE]
val isAeReady = (
aeState == null // May be null in some devices (e.g. legacy camera HW level)
|| aeState == CaptureResult.CONTROL_AE_STATE_CONVERGED
|| aeState == CaptureResult.CONTROL_AE_STATE_FLASH_REQUIRED
)
val isAwbReady = (
awbState == null // May be null in some devices (e.g. legacy camera HW level)
|| awbState == CaptureResult.CONTROL_AWB_STATE_CONVERGED
)
if (isAeReady && isAwbReady) {
// if any non-null convergenceDeferred is set, complete it
it.complete(Unit)
}
}
}
override fun onCaptureCompleted(
session: CameraCaptureSession,
request: CaptureRequest,
result: TotalCaptureResult
) {
super.onCaptureCompleted(session, request, result)
process(result)
}
}
Java
static class AwaitingCaptureCallback extends CameraCaptureSession.CaptureCallback {
private int mTargetAeMode;
private CountDownLatch mAeModeUpdateLatch = null;
private CountDownLatch mConvergenceLatch = null;
public void awaitAeModeUpdate(int targetAeMode) {
mTargetAeMode = targetAeMode;
mAeModeUpdateLatch = new CountDownLatch(1);
// Makes the current thread wait until mAeModeUpdateLatch is released, it will be
// released once targetAeMode is found in the capture callbacks below
try {
mAeModeUpdateLatch.await();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public void awaitAeAwbConvergence() {
mConvergenceLatch = new CountDownLatch(1);
// Makes the current coroutine wait until mConvergenceLatch is released, it will be
// released once both AE & AWB are reported as converged in the capture callbacks below
try {
mConvergenceLatch.await();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
private void process(CaptureResult result) {
// Checks if AE mode is updated and decrements the count of any awaiting latch
if (mAeModeUpdateLatch != null) {
int aeMode = result.get(CaptureResult.CONTROL_AE_MODE);
if (aeMode == mTargetAeMode) {
mAeModeUpdateLatch.countDown();
}
}
// Checks for convergence and decrements the count of any awaiting latch
if (mConvergenceLatch != null) {
Integer aeState = result.get(CaptureResult.CONTROL_AE_STATE);
Integer awbState = result.get(CaptureResult.CONTROL_AWB_STATE);
boolean isAeReady = (
aeState == null // May be null in some devices (e.g. legacy camera HW level)
|| aeState == CaptureResult.CONTROL_AE_STATE_CONVERGED
|| aeState == CaptureResult.CONTROL_AE_STATE_FLASH_REQUIRED
);
boolean isAwbReady = (
awbState == null // May be null in some devices (e.g. legacy camera HW level)
|| awbState == CaptureResult.CONTROL_AWB_STATE_CONVERGED
);
if (isAeReady && isAwbReady) {
mConvergenceLatch.countDown();
mConvergenceLatch = null;
}
}
}
@Override
public void onCaptureCompleted(@NonNull CameraCaptureSession session,
@NonNull CaptureRequest request,
@NonNull TotalCaptureResult result) {
super.onCaptureCompleted(session, request, result);
process(result);
}
}
在相机设置期间将回调设置为重复请求
以下代码示例允许您在初始化期间将回调设置为重复请求。
Kotlin
// Open the selected camera
camera = openCamera(cameraManager, cameraId, cameraHandler)
// Creates list of Surfaces where the camera will output frames
val targets = listOf(previewSurface, imageReaderSurface)
// Start a capture session using our open camera and list of Surfaces where frames will go
session = createCameraCaptureSession(camera, targets, cameraHandler)
val captureRequest = camera.createCaptureRequest(
CameraDevice.TEMPLATE_PREVIEW).apply { addTarget(previewSurface) }
// This will keep sending the capture request as frequently as possible until the
// session is torn down or session.stopRepeating() is called
session.setRepeatingRequest(captureRequest.build(), repeatingCaptureCallback, cameraHandler)
Java
// Open the selected camera mCamera = openCamera(mCameraManager, mCameraId, mCameraHandler); // Creates list of Surfaces where the camera will output frames Listtargets = new ArrayList<>(Arrays.asList(mPreviewSurface, mImageReaderSurface)); // Start a capture session using our open camera and list of Surfaces where frames will go mSession = createCaptureSession(mCamera, targets, mCameraHandler); try { CaptureRequest.Builder requestBuilder = mCamera.createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW); requestBuilder.addTarget(mPreviewSurface); // This will keep sending the capture request as frequently as possible until the // session is torn down or session.stopRepeating() is called mSession.setRepeatingRequest(requestBuilder.build(), mRepeatingCaptureCallback, mCameraHandler); } catch (CameraAccessException e) { e.printStackTrace(); }
预捕获序列触发和等待
设置好回调后，您可以使用以下代码示例进行预捕获序列触发和等待。
Kotlin
private suspend fun runPrecaptureSequence() {
// Creates a new capture request with CONTROL_AE_PRECAPTURE_TRIGGER_START
val captureRequest = session.device.createCaptureRequest(
CameraDevice.TEMPLATE_PREVIEW
).apply {
addTarget(previewSurface)
set(
CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER,
CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER_START
)
}
val precaptureDeferred = CompletableDeferred()
session.capture(captureRequest.build(), object: CameraCaptureSession.CaptureCallback() {
override fun onCaptureCompleted(
session: CameraCaptureSession,
request: CaptureRequest,
result: TotalCaptureResult
) {
// Waiting for this callback ensures the precapture request has been processed
precaptureDeferred.complete(Unit)
}
}, cameraHandler)
precaptureDeferred.await()
// Precapture trigger request has been processed, we can wait for AE & AWB convergence now
repeatingCaptureCallback.awaitAeAwbConvergence()
}
Java
private void runPrecaptureSequence() {
// Creates a new capture request with CONTROL_AE_PRECAPTURE_TRIGGER_START
try {
CaptureRequest.Builder requestBuilder =
mSession.getDevice().createCaptureRequest(CameraDevice.TEMPLATE_PREVIEW);
requestBuilder.addTarget(mPreviewSurface);
requestBuilder.set(CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER,
CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER_START);
CountDownLatch precaptureLatch = new CountDownLatch(1);
mSession.capture(requestBuilder.build(), new CameraCaptureSession.CaptureCallback() {
@Override
public void onCaptureCompleted(@NonNull CameraCaptureSession session,
@NonNull CaptureRequest request,
@NonNull TotalCaptureResult result) {
Log.d(TAG, "CONTROL_AE_PRECAPTURE_TRIGGER_START processed");
// Waiting for this callback ensures the precapture request has been processed
precaptureLatch.countDown();
}
}, mCameraHandler);
precaptureLatch.await();
// Precapture trigger request has been processed, we can wait for AE & AWB convergence now
mRepeatingCaptureCallback.awaitAeAwbConvergence();
} catch (CameraAccessException | InterruptedException e) {
e.printStackTrace();
}
}
将所有内容组合在一起
准备就绪所有主要组件后，无论何时需要拍摄照片，例如当用户点击捕获按钮拍摄照片时，所有步骤都可以按照前面讨论和代码示例中提到的顺序执行。
Kotlin
// User clicks captureButton to take picture
captureButton.setOnClickListener { v ->
// Apply the screen flash related UI changes
whiteColorOverlayView.visibility = View.VISIBLE
maximizeScreenBrightness()
// Perform I/O heavy operations in a different scope
lifecycleScope.launch(Dispatchers.IO) {
// Enable external flash AE mode and wait for it to be processed
enableExternalFlashAeMode()
// Run precapture sequence and wait for it to complete
runPrecaptureSequence()
// Start taking picture and wait for it to complete
takePhoto()
disableExternalFlashAeMode()
v.post {
// Clear the screen flash related UI changes
restoreScreenBrightness()
whiteColorOverlayView.visibility = View.INVISIBLE
}
}
}
Java
// User clicks captureButton to take picture
mCaptureButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
// Apply the screen flash related UI changes
mWhiteColorOverlayView.setVisibility(View.VISIBLE);
maximizeScreenBrightness();
// Perform heavy operations in a different thread
Executors.newSingleThreadExecutor().execute(() -> {
// Enable external flash AE mode and wait for it to be processed
enableExternalFlashAeMode();
// Run precapture sequence and wait for it to complete
runPrecaptureSequence();
// Start taking picture and wait for it to complete
takePhoto();
disableExternalFlashAeMode();
v.post(() -> {
// Clear the screen flash related UI changes
restoreScreenBrightness();
mWhiteColorOverlayView.setVisibility(View.INVISIBLE);
});
});
}
});
示例图片
您可以从以下示例中看到，错误实现和正确实现屏幕闪光灯时的结果。
错误操作时
如果屏幕闪光灯未正确实现，您将在多次捕获、设备和照明条件下获得不一致的结果。通常，捕获的图像会出现曝光不良或色调问题。对于某些设备，这些类型的错误在特定照明条件下会更加明显，例如弱光环境而不是完全黑暗的环境。
下表显示了此类问题的示例。它们是在 CameraX 实验室基础设施中拍摄的，光源保持暖白色。此暖白色光源让您了解蓝色色调实际上是一个问题，而不是光源的副作用。
| 环境 | 曝光不足 | 曝光过度 | 色调 |
|---|---|---|---|
| 黑暗环境（没有光源，只有手机） |
|
|
|
| 弱光（额外的约 3 勒克斯光源） |
|
|
|
正确操作时
当使用标准实现方法针对相同的设备和条件进行操作时，您可以在下表中看到结果。
| 环境 | 曝光不足（已修复） | 曝光过度（已修复） | 色调（已修复） |
|---|---|---|---|
| 黑暗环境（没有光源，只有手机） |
|
|
|
| 弱光（额外的约 3 勒克斯光源） |
|
|
|
如观察到的，使用标准实现方法，图像质量有了显著提高。