Мигание экрана

Мигание экрана, также называемое передней вспышкой или вспышкой для селфи, использует яркость экрана телефона для освещения объекта при съемке изображений с помощью фронтальной камеры в условиях низкой освещенности. Она доступна во многих приложениях для камеры и социальных сетей. Поскольку большинство людей держат телефон достаточно близко, когда делают селфи, этот подход эффективен.

Однако разработчикам сложно реализовать эту функцию должным образом и поддерживать хорошее качество записи на разных устройствах. В этом руководстве показано, как правильно реализовать эту функцию с помощью Camera2 – низкоуровневого API фреймворка камеры Android.

Общий рабочий процесс

Чтобы правильно реализовать эту функцию, необходимо использовать последовательность замера перед съемкой (автоматическая экспозиция перед съемкой) и правильно рассчитать время операций. Общий рабочий процесс показан на рисунке 1.

Блок-схема, показывающая, как интерфейс мигания экрана используется в Camera2.
Рисунок 1. Общий рабочий процесс для реализации мигания экрана.

Ниже описано, как сделать снимок с помощью функции мигания экрана.

  1. Примените изменения интерфейса, необходимые для работы вспышки экрана, которая может обеспечить достаточное освещение для съемки. Для общих случаев Google предлагает следующие изменения интерфейса, которые использовались в наших тестах:
    • Экран приложения закрыт белым оверлеем.
    • Яркость экрана установлена на максимум.
  2. Установите режим автоматической экспозиции (AE) на CONTROL_AE_MODE_ON_EXTERNAL_FLASH, если он поддерживается.
  3. Запустите предварительную оценку экспозиции с помощью CONTROL_AE_PRECAPTURE_TRIGGER.
  4. Дождитесь, пока автоэкспозиция и автоматический баланс белого не будут сведены.

  5. После этого используется обычный процесс съемки.

  6. Отправка запроса на захват в фреймворк.

  7. Дождитесь результата.

  8. Сбросить режим автоэкспозиции, если было задано значение CONTROL_AE_MODE_ON_EXTERNAL_FLASH.

  9. Очистить изменения интерфейса для мигания экрана.

Образцы кода Camera2

Экран приложения закрыт белым оверлеем

Добавьте View в XML-файл макета приложения. У него достаточная высота, чтобы находиться поверх всех остальных элементов интерфейса во время съемки с миганием экрана. По умолчанию он скрыт и становится виден, только когда применяются изменения интерфейса мигания экрана.

В примере кода ниже в качестве цвета представления используется белый (#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 WindowManager в ссылке Activity Window.

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

Установить режим автоэкспозиции CONTROL_AE_MODE_ON_EXTERNAL_FLASH

CONTROL_AE_MODE_ON_EXTERNAL_FLASH доступен для уровня API 28 и выше. Однако этот режим доступен не на всех устройствах, поэтому проверьте, доступен ли он, и установите соответствующее значение. Чтобы проверить доступность, используйте CameraCharacteristics#CONTROL_AE_AVAILABLE_MODES.

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

Если в приложении настроен повторяющийся запрос на захват (это необходимо для предварительного просмотра), режим AE должен быть установлен на повторяющийся запрос. В противном случае при следующем повторном захвате он может быть переопределен режимом AE по умолчанию или другим режимом, установленным пользователем. В этом случае у камеры может не хватить времени на выполнение всех операций, которые она обычно выполняет в режиме автоматической экспозиции с внешней вспышкой.

Чтобы убедиться, что камера полностью обработала запрос на обновление режима AE, проверьте результат съемки в обратном вызове повторяющейся съемки и дождитесь обновления режима AE в результате.

Обратный вызов захвата, который может ожидать обновления режима AE

В приведенном ниже фрагменте кода показано, как это сделать.

private val repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {
    private var targetAeMode: Int? = null
    private var aeModeUpdateDeferred: CompletableDeferred<Unit>? = 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)
    }
}

Настройте повторяющийся запрос, чтобы включить или отключить режим AE.

В приведенных ниже примерах кода показано, как настроить повторяющийся запрос с помощью обратного вызова.

/** [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
        )
    }
}

Как запустить предварительную съемку

Чтобы запустить последовательность замера перед съемкой, отправьте CaptureRequest со значением CONTROL_AE_PRECAPTURE_TRIGGER_START, заданным для запроса. Дождитесь обработки запроса и схождения AE и AWB.

Хотя предварительная съемка запускается одним запросом на съемку, ожидание сходимости AE и AWB требует большей сложности. Вы можете отслеживать состояние автоматической экспозиции и состояние автоматического баланса белого с помощью обратного вызова захвата, настроенного на повторяющийся запрос.

Обновление одного и того же повторяющегося обратного вызова позволяет упростить код. Приложениям часто требуется предварительный просмотр, для которого они настраивают повторяющийся запрос при настройке камеры. Таким образом, вы можете установить обратный вызов повторяющегося захвата для этого начального повторяющегося запроса один раз, а затем повторно использовать его для проверки результатов и целей ожидания.

Обновление кода обратного вызова для ожидания конвергенции

Чтобы обновить обратный вызов повторяющейся съемки, используйте следующий фрагмент кода:

private val repeatingCaptureCallback = object : CameraCaptureSession.CaptureCallback() {
    private var targetAeMode: Int? = null
    private var aeModeUpdateDeferred: CompletableDeferred<Unit>? = null

    private var convergenceDeferred: CompletableDeferred<Unit>? = 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)
    }
}

Установите обратный вызов для повторяющегося запроса во время настройки камеры.

В приведенном ниже примере кода показано, как настроить обратный вызов для повторяющегося запроса во время инициализации.

// 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)

Запуск и ожидание последовательности предварительной съемки

После настройки обратного вызова вы можете использовать следующий пример кода для запуска и ожидания последовательности предварительной съемки.

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<Unit>()
    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()
}

Объедините все вместе

Когда все основные компоненты готовы, каждый раз, когда нужно сделать снимок, например когда пользователь нажимает кнопку съемки, все шаги могут выполняться в порядке, указанном в предыдущем обсуждении и примерах кода.

// User clicks captureButton to take picture.
captureButton.setOnClickListener {
    // Apply the screen flash related UI changes.
    whiteColorOverlayView.visibility = View.VISIBLE
    maximizeScreenBrightness()

    // Launch on the main thread, then switch to IO for background operations.
    lifecycleScope.launch {
        // Perform I/O heavy operations in a different scope.
        withContext(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()
        }

        // Back on the main thread automatically.
        // Clear the screen flash related UI changes.
        restoreScreenBrightness()
        whiteColorOverlayView.visibility = View.INVISIBLE
    }
}

Образцы изображений

Ниже приведены примеры того, что происходит, когда мигание экрана реализовано неправильно и когда оно реализовано правильно.

Неправильный подход

Если мигание экрана реализовано неправильно, вы получите противоречивые результаты при нескольких съемках, на разных устройствах и в разных условиях освещения. Часто у снятых изображений есть проблемы с экспозицией или оттенком цвета. На некоторых устройствах такие ошибки становятся более очевидными при определенных условиях освещения, например при слабом освещении, а не в полной темноте.

В таблице ниже приведены примеры таких проблем. Они сделаны в лаборатории CameraX с источниками теплого белого света. Этот источник теплого белого света позволяет увидеть, что синий оттенок – это реальная проблема, а не побочный эффект источника света.

Среда Недодержка Передержка Оттенок цвета
Темная среда (нет источника света, кроме телефона) Почти полностью темная фотография Слишком светлая фотография Фотография с фиолетовым оттенком
Слабое освещение (дополнительный источник света около 3 люкс) Темноватая фотография Слишком светлая фотография Фотография с синеватым оттенком

Если все сделано правильно,

Если для тех же устройств и условий используется стандартная реализация, результаты будут такими, как показано в таблице ниже.

Среда Недостаточная экспозиция (исправлено) Передержка (исправлено) Оттенок цвета (фиксированный)
Темная среда (нет источника света, кроме телефона) Удалить фото Удалить фото Четкое фото без оттенков
Слабое освещение (дополнительный источник света около 3 люкс) Удалить фото Удалить фото Четкая фотография без оттенка.

Как видно, качество изображения значительно улучшается при стандартной реализации.