Added in API level 31

CameraExtensionCharacteristics

class CameraExtensionCharacteristics
kotlin.Any
   ↳ android.hardware.camera2.CameraExtensionCharacteristics

Allows clients to query availability and supported resolutions of camera extensions.

Camera extensions give camera clients access to device-specific algorithms and sequences that can improve the overall image quality of snapshots in various cases such as low light, selfies, portraits, and scenes that can benefit from enhanced dynamic range. Often such sophisticated processing sequences will rely on multiple camera frames as input and will produce a single output.

Camera extensions are not guaranteed to be present on all devices so camera clients must query for their availability via CameraExtensionCharacteristics#getSupportedExtensions().

In order to use any available camera extension, camera clients must create a corresponding CameraExtensionSession via CameraDevice#createExtensionSession(ExtensionSessionConfiguration)

Camera clients must be aware that device-specific camera extensions may support only a subset of the available camera resolutions and must first query CameraExtensionCharacteristics#getExtensionSupportedSizes(int, int) for supported single high-quality request output sizes and CameraExtensionCharacteristics#getExtensionSupportedSizes(int, Class) for supported repeating request output sizes.

The extension characteristics for a given device are expected to remain static under normal operating conditions.

Summary

Constants
static Int

Device-specific extension implementation for automatic selection of particular extension such as HDR or NIGHT depending on the current lighting and environment conditions.
static Int

Device-specific extension implementation which tends to smooth the skin and apply other cosmetic effects to people's faces.
static Int

Device-specific extension implementation which can blur certain regions of the final image thereby "enhancing" focus for all remaining non-blurred parts.
static Int

Device-specific extension implementation which tends to smooth the skin and apply other cosmetic effects to people's faces.
static Int

Device-specific extension implementation for enhancing the dynamic range of the final image.
static Int

Device-specific extension implementation that aims to suppress noise and improve the overall image quality under low light conditions.
Public methods
T
get(extension: Int, key: CameraCharacteristics.Key<T>)

Gets an extension specific camera characteristics field value.
MutableSet<CaptureRequest.Key<Any!>!>

Returns the set of keys supported by a CaptureRequest submitted in a CameraExtensionSession with a given extension type.
MutableSet<CaptureResult.Key<Any!>!>

Returns the set of keys supported by a CaptureResult passed as an argument to CameraExtensionSession.ExtensionCaptureCallback#onCaptureResultAvailable.
Range<Long!>?
getEstimatedCaptureLatencyRangeMillis(extension: Int, captureOutputSize: Size, format: Int)

Returns the estimated capture latency range in milliseconds for the target capture resolution during the calls to CameraExtensionSession#capture.
MutableList<Size!>
getExtensionSupportedSizes(extension: Int, klass: Class<T>)

Get a list of sizes compatible with klass to use as an output for the repeating request CameraExtensionSession#setRepeatingRequest.
MutableList<Size!>
getExtensionSupportedSizes(extension: Int, format: Int)

Check whether a given extension is available and return the supported output surface resolutions that can be used for high-quality capture requests via CameraExtensionSession#capture.
MutableSet<CameraCharacteristics.Key<Any!>!>
getKeys(extension: Int)

Returns the CameraCharacteristics keys that have extension-specific values.
MutableList<Size!>
getPostviewSupportedSizes(extension: Int, captureSize: Size, format: Int)

Get a list of the postview sizes supported for a still capture, using its capture size captureSize, to use as an output for the postview request.
MutableList<Int!>

Return a list of supported device-specific extensions for a given camera device.
Boolean

Retrieve support for capture progress callbacks via CameraExtensionSession.ExtensionCaptureCallback#onCaptureProcessProgressed.
Boolean

Checks for postview support of still capture.

Constants

EXTENSION_AUTOMATIC

Added in API level 31
static val EXTENSION_AUTOMATIC: Int

Device-specific extension implementation for automatic selection of particular extension such as HDR or NIGHT depending on the current lighting and environment conditions.

Value: 0

EXTENSION_BEAUTY

Added in API level 31
Deprecated in API level 33
static val EXTENSION_BEAUTY: Int

Deprecated: Use EXTENSION_FACE_RETOUCH instead.

Device-specific extension implementation which tends to smooth the skin and apply other cosmetic effects to people's faces.

Value: 1

EXTENSION_BOKEH

Added in API level 31
static val EXTENSION_BOKEH: Int

Device-specific extension implementation which can blur certain regions of the final image thereby "enhancing" focus for all remaining non-blurred parts.

Value: 2

EXTENSION_FACE_RETOUCH

Added in API level 33
static val EXTENSION_FACE_RETOUCH: Int

Device-specific extension implementation which tends to smooth the skin and apply other cosmetic effects to people's faces.

Value: 1

EXTENSION_HDR

Added in API level 31
static val EXTENSION_HDR: Int

Device-specific extension implementation for enhancing the dynamic range of the final image.

Value: 3

EXTENSION_NIGHT

Added in API level 31
static val EXTENSION_NIGHT: Int

Device-specific extension implementation that aims to suppress noise and improve the overall image quality under low light conditions.

Value: 4

Public methods

get

Added in API level 35
fun <T : Any!> get(
    extension: Int, 
    key: CameraCharacteristics.Key<T>
): T

Gets an extension specific camera characteristics field value.

An extension can have a reduced set of camera capabilities (such as limited zoom ratio range, available video stabilization modes, etc). This API enables applications to query for an extension’s specific camera characteristics. Applications are recommended to prioritize obtaining camera characteristics using this API when using an extension. A null result indicates that the extension specific characteristic is not defined or available.

Parameters
extension Int: The extension type. Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
key CameraCharacteristics.Key<T>: The characteristics field to read. This value cannot be null.
Return
T The value of that key, or null if the field is not set.
Exceptions
java.lang.IllegalArgumentException if the key is not valid or extension type is not a supported device-specific extension.

getAvailableCaptureRequestKeys

Added in API level 33
fun getAvailableCaptureRequestKeys(extension: Int): MutableSet<CaptureRequest.Key<Any!>!>

Returns the set of keys supported by a CaptureRequest submitted in a CameraExtensionSession with a given extension type.

The set returned is not modifiable, so any attempts to modify it will throw a UnsupportedOperationException.

Devices launching on Android android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM or newer versions are required to support CaptureRequest#CONTROL_AF_MODE, CaptureRequest#CONTROL_AF_REGIONS, CaptureRequest#CONTROL_AF_TRIGGER, CaptureRequest#CONTROL_ZOOM_RATIO for CameraExtensionCharacteristics#EXTENSION_NIGHT.

Parameters
extension Int: the extension type Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
Return
MutableSet<CaptureRequest.Key<Any!>!> non-modifiable set of capture keys supported by camera extension session initialized with the given extension type. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException in case of unsupported extension.

getAvailableCaptureResultKeys

Added in API level 33
fun getAvailableCaptureResultKeys(extension: Int): MutableSet<CaptureResult.Key<Any!>!>

Returns the set of keys supported by a CaptureResult passed as an argument to CameraExtensionSession.ExtensionCaptureCallback#onCaptureResultAvailable.

The set returned is not modifiable, so any attempts to modify it will throw a UnsupportedOperationException.

In case the set is empty, then the extension is not able to support any capture results and the CameraExtensionSession.ExtensionCaptureCallback#onCaptureResultAvailable callback will not be fired.

Devices launching on Android android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM or newer versions are required to support CaptureResult#CONTROL_AF_MODE, CaptureResult#CONTROL_AF_REGIONS, CaptureResult#CONTROL_AF_TRIGGER, CaptureResult#CONTROL_AF_STATE, CaptureResult#CONTROL_ZOOM_RATIO for CameraExtensionCharacteristics#EXTENSION_NIGHT.

Parameters
extension Int: the extension type Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
Return
MutableSet<CaptureResult.Key<Any!>!> non-modifiable set of capture result keys supported by camera extension session initialized with the given extension type. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException in case of unsupported extension.

getEstimatedCaptureLatencyRangeMillis

Added in API level 31
fun getEstimatedCaptureLatencyRangeMillis(
    extension: Int, 
    captureOutputSize: Size, 
    format: Int
): Range<Long!>?

Returns the estimated capture latency range in milliseconds for the target capture resolution during the calls to CameraExtensionSession#capture. This includes the time spent processing the multi-frame capture request along with any additional time for encoding of the processed buffer if necessary.

Parameters
extension Int: the extension type Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
captureOutputSize Size: size of the capture output surface. If it is not in the supported output sizes, maximum capture output size is used for the estimation This value cannot be null.
format Int: device-specific extension output format Value is android.graphics.ImageFormat#UNKNOWN, android.graphics.PixelFormat#RGBA_8888, android.graphics.PixelFormat#RGBX_8888, android.graphics.PixelFormat#RGB_888, android.graphics.ImageFormat#RGB_565, android.graphics.ImageFormat#YV12, android.graphics.ImageFormat#Y8, android.graphics.ImageFormat.Y16, android.graphics.ImageFormat#YCBCR_P010, android.graphics.ImageFormat#NV16, android.graphics.ImageFormat#NV21, android.graphics.ImageFormat#YUY2, android.graphics.ImageFormat#JPEG, android.graphics.ImageFormat#DEPTH_JPEG, android.graphics.ImageFormat#YUV_420_888, android.graphics.ImageFormat#YUV_422_888, android.graphics.ImageFormat#YUV_444_888, android.graphics.ImageFormat#FLEX_RGB_888, android.graphics.ImageFormat#FLEX_RGBA_8888, android.graphics.ImageFormat#RAW_SENSOR, android.graphics.ImageFormat#RAW_PRIVATE, android.graphics.ImageFormat#RAW10, android.graphics.ImageFormat#RAW12, android.graphics.ImageFormat#DEPTH16, android.graphics.ImageFormat#DEPTH_POINT_CLOUD, android.graphics.ImageFormat.RAW_DEPTH, android.graphics.ImageFormat.RAW_DEPTH10, android.graphics.ImageFormat#PRIVATE, android.graphics.ImageFormat#HEIC, or android.graphics.ImageFormat#JPEG_R
Return
Range<Long!>? the range of estimated minimal and maximal capture latency in milliseconds or null if no capture latency info can be provided
Exceptions
java.lang.IllegalArgumentException in case of format different from ImageFormat#JPEG, ImageFormat#YUV_420_888, ImageFormat#JPEG_R ImageFormat#YCBCR_P010; or unsupported extension.

getExtensionSupportedSizes

Added in API level 31
fun <T : Any!> getExtensionSupportedSizes(
    extension: Int, 
    klass: Class<T>
): MutableList<Size!>

Get a list of sizes compatible with klass to use as an output for the repeating request CameraExtensionSession#setRepeatingRequest.

Note that device-specific extensions are allowed to support only a subset of the camera output surfaces and resolutions. The android.graphics.SurfaceTexture class is guaranteed at least one size for backward compatible cameras whereas other output classes are not guaranteed to be supported.

Starting with Android android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE android.view.SurfaceView classes are also guaranteed to be supported and include the same resolutions as android.graphics.SurfaceTexture. Clients must set the desired SurfaceView resolution by calling android.view.SurfaceHolder#setFixedSize.

Parameters
extension Int: the extension type Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
klass Class<T>: a non-null Class object reference
Return
MutableList<Size!> non-modifiable list of available sizes or an empty list if the Surface output is not supported This value cannot be null.
Exceptions
java.lang.NullPointerException if klass was null
java.lang.IllegalArgumentException in case of unsupported extension.

getExtensionSupportedSizes

Added in API level 31
fun getExtensionSupportedSizes(
    extension: Int, 
    format: Int
): MutableList<Size!>

Check whether a given extension is available and return the supported output surface resolutions that can be used for high-quality capture requests via CameraExtensionSession#capture.

Note that device-specific extensions are allowed to support only a subset of the camera resolutions advertised by android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes.

Device-specific extensions currently support at most three multi-frame capture surface formats. ImageFormat.JPEG will be supported by all extensions while ImageFormat.YUV_420_888, ImageFormat.JPEG_R, or ImageFormat.YCBCR_P010 may or may not be supported.

Parameters
extension Int: the extension type Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
format Int: device-specific extension output format
Return
MutableList<Size!> non-modifiable list of available sizes or an empty list if the format is not supported. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException in case of format different from ImageFormat.JPEG, ImageFormat.YUV_420_888, ImageFormat.JPEG_R, ImageFormat.YCBCR_P010; or unsupported extension.

getKeys

Added in API level 35
fun getKeys(extension: Int): MutableSet<CameraCharacteristics.Key<Any!>!>

Returns the CameraCharacteristics keys that have extension-specific values.

An application can query the value from the key using get(int,android.hardware.camera2.CameraCharacteristics.Key) API.

Parameters
extension Int: The extension type. Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
Return
MutableSet<CameraCharacteristics.Key<Any!>!> An unmodifiable set of keys that are extension specific. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException in case the extension type is not a supported device-specific extension

getPostviewSupportedSizes

Added in API level 34
fun getPostviewSupportedSizes(
    extension: Int, 
    captureSize: Size, 
    format: Int
): MutableList<Size!>

Get a list of the postview sizes supported for a still capture, using its capture size captureSize, to use as an output for the postview request.

Available postview sizes will always be either equal to or less than the still capture size. When choosing the most applicable postview size for a usecase, it should be noted that lower resolution postviews will generally be available more quickly than larger resolution postviews. For example, when choosing a size for an optimized postview that will be displayed as a placeholder while the final image is processed, the resolution closest to the preview size may be most suitable.

Note that device-specific extensions are allowed to support only a subset of the camera resolutions advertised by android.hardware.camera2.params.StreamConfigurationMap#getOutputSizes.

Parameters
extension Int: the extension type Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
captureSize Size: size of the still capture for which the postview is requested This value cannot be null.
format Int: device-specific extension output format of the postview
Return
MutableList<Size!> non-modifiable list of available sizes or an empty list if the format and size is not supported. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException in case of unsupported extension or if postview feature is not supported by extension.

getSupportedExtensions

Added in API level 31
fun getSupportedExtensions(): MutableList<Int!>

Return a list of supported device-specific extensions for a given camera device.

Return
MutableList<Int!> non-modifiable list of available extensions This value cannot be null.

isCaptureProcessProgressAvailable

Added in API level 34
fun isCaptureProcessProgressAvailable(extension: Int): Boolean

Retrieve support for capture progress callbacks via CameraExtensionSession.ExtensionCaptureCallback#onCaptureProcessProgressed.

Parameters
extension Int: the extension type Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
Return
Boolean true in case progress callbacks are supported, false otherwise
Exceptions
java.lang.IllegalArgumentException in case of an unsupported extension.

isPostviewAvailable

Added in API level 34
fun isPostviewAvailable(extension: Int): Boolean

Checks for postview support of still capture.

A postview is a preview version of the still capture that is available before the final image. For example, it can be used as a temporary placeholder for the requested capture while the final image is being processed. The supported sizes for a still capture's postview can be retrieved using CameraExtensionCharacteristics#getPostviewSupportedSizes(int, Size, int).

Starting with Android android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM, the formats of the still capture and postview are not required to be equivalent upon capture request.

Parameters
extension Int: the extension type Value is either 0 or a combination of android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_AUTOMATIC, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_FACE_RETOUCH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_BOKEH, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_HDR, android.hardware.camera2.CameraExtensionCharacteristics#EXTENSION_NIGHT, and android.hardware.camera2.CameraExtensionCharacteristics.EXTENSION_EYES_FREE_VIDEOGRAPHY
Return
Boolean true in case postview is supported, false otherwise
Exceptions
java.lang.IllegalArgumentException in case the extension type is not a supported device-specific extension