ImageCapture.ScreenFlash


interface ImageCapture.ScreenFlash


Interface to do the application changes required for screen flash operations.

Each apply invocation will be followed up with a corresponding clear invocation. For each image capture, #apply and #clear will be invoked only once.

Summary

Public functions

Unit
@UiThread
apply(
    expirationTimeMillis: Long,
    screenFlashListener: ImageCapture.ScreenFlashListener
)

Applies the necessary application changes for a screen flash photo capture.

Unit

Clears any application change done for screen flash operation, if required.

Public functions

apply

Added in 1.4.0
@UiThread
fun apply(
    expirationTimeMillis: Long,
    screenFlashListener: ImageCapture.ScreenFlashListener
): Unit

Applies the necessary application changes for a screen flash photo capture.

When the application UI needs to be changed for a successful photo capture with screen flash feature, CameraX will invoke this method and wait for the application to complete its changes. When this API is invoked, the application UI should utilize the screen to provide extra light as an alternative to physical flash. For example, the screen brightness can be maximized and screen color can be covered with some bright color like white.

The parameter expirationTimeMillis is based on currentTimeMillis. It is at least 3 seconds later from the start of a screen flash image capture operation. Until the timestamp of expirationTimeMillis parameter, CameraX will wait for the application to notify the completion of the application-side changes using the ScreenFlashListener parameter of this method. Applications must call onCompleted after their UI changes are done so that CameraX is not unnecessarily waiting. If the application does not call ScreenFlashListener#onCompleted before expirationTimeMillis, CameraX will stop waiting and move forward with the subsequent operations regardless. In such case, the application no longer needs to call ScreenFlashListener#onCompleted(). If clear has also been invoked while the application is still doing the changes, it is the application's responsibility to clear any UI change done after clear has been invoked.

The following code snippet shows an example implementation of this API.


public void apply(long expirationTimeMillis,
        ScreenFlashListener screenFlashListener) {
    // Enable top overlay to make screen color white
    whiteColorOverlay.setVisible(true);
    // Maximize screen brightness
    maximizeScreenBrightness();
    screenFlashListener.onCompleted();
}
Parameters
expirationTimeMillis: Long

The timestamp after which CameraX will no longer listen to screenFlashListener.

screenFlashListener: ImageCapture.ScreenFlashListener

Used to notify when UI changes have been applied.

clear

Added in 1.4.0
@UiThread
fun clear(): Unit

Clears any application change done for screen flash operation, if required.

CameraX will invoke this method when a screen flash photo capture has been completed and the application screen can be safely changed to a state not conforming to screen flash photo capture.