Camera bokeh

Camera bokeh is a shallow depth-of-field effect created by blurring out parts of a scene so that they're not in focus. On cameras on mobile devices, bokeh is achieved using depth information acquired from the stereo vision from two cameras or from dual photodiodes (PDs) of a single camera.

Starting from Android 11, the Android platform supports bokeh implementations and provides APIs to make the feature available to third-party apps.

Implementation

To make the camera bokeh feature available on your device, do the following:

  • Advertise ANDROID_CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_MAX_SIZES:

    This tag is in the format of a three-integer tuple array, with each tuple in the format of {mode, maxWidth, maxHeight}. In addition to {ANDROID_CONTROL_EXTENDED_SCENE_MODE_DISABLED, 0, 0}, the camera HAL must also list one or both of the ANDROID_CONTROL_EXTENDED_SCENE_MODE_BOKEH_STILL_CAPTURE and ANDROID_CONTROL_EXTENDED_SCENE_MODE_BOKEH_CONTINUOUS modes with their corresponding maximum streaming sizes.

  • Advertise ANDROID_CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_ZOOM_RATIO_RANGES:

    This tag is in the format of a {minZoomRatio, maxZoomRatio} array, which contains all the zoom ratio ranges for an enabled extended scene mode, in the same order as in ANDROID_CONTROL_AVAILABLE_EXTENDED_SCENE_MODE_MAX_SIZES. A zoom range of [1.0, 1.0] means that zoom isn't supported.

  • Populate ANDROID_CONTROL_USE_EXTENDED_SCENE_MODE in ANDROID_CONTROL_AVAILABLE_MODES.

For an app to trigger the bokeh feature, the app must set ANDROID_CONTROL_MODE to ANDROID_CONTROL_USE_EXTENDED_SCENE_MODE and ANDROID_CONTROL_EXTENDED_SCENE_MODE to one of supported extended scene modes. Note that implementing bokeh might lead to extra memory consumption because of stereo computation.

If a supported extended scene mode can't be applied per frame and results in unexpected delays when enabled/disabled, include ANDROID_CONTROL_EXTENDED_SCENE_MODE in ANDROID_REQUEST_AVAILABLE_SESSION_KEYS. At the same time, implement the ICameraDeviceSession::isReconfigurationRequired() method to avoid reconfiguration for extended scene modes that don't require reconfiguration.

Validation

To validate the bokeh feature on your device, run the following CTS, VTS, and CTS Verifier tests:

  • CtsCameraTestCases
  • VtsHalCameraProviderV2_4TargetTest
  • CameraBokehTest in CTS Verifier