CameraExtensionCharacteristics  |  API reference  |  Android Developers (original) (raw)

public final class CameraExtensionCharacteristics
extends [Object](/reference/java/lang/Object) ``

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()](/reference/android/hardware/camera2/CameraExtensionCharacteristics#getSupportedExtensions%28%29).

In order to use any available camera extension, camera clients must create a corresponding[CameraExtensionSession](/reference/android/hardware/camera2/CameraExtensionSession) via[CameraDevice.createExtensionSession(ExtensionSessionConfiguration)](/reference/android/hardware/camera2/CameraDevice#createExtensionSession%28android.hardware.camera2.params.ExtensionSessionConfiguration%29)

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)](/reference/android/hardware/camera2/CameraExtensionCharacteristics#getExtensionSupportedSizes%28int,%20int%29) for supported single high-quality request output sizes and[CameraExtensionCharacteristics.getExtensionSupportedSizes(int,Class)](/reference/android/hardware/camera2/CameraExtensionCharacteristics#getExtensionSupportedSizes%28int,%20java.lang.Class<T>%29) for supported repeating request output sizes.

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

Summary

Constants
int EXTENSION_AUTOMATIC Device-specific extension implementation for automatic selection of particular extension such as HDR or NIGHT depending on the current lighting and environment conditions.
int EXTENSION_BEAUTY This constant was deprecated in API level 33. Use EXTENSION_FACE_RETOUCH instead.
int EXTENSION_BOKEH Device-specific extension implementation which can blur certain regions of the final image thereby "enhancing" focus for all remaining non-blurred parts.
int EXTENSION_FACE_RETOUCH Device-specific extension implementation which tends to smooth the skin and apply other cosmetic effects to people's faces.
int EXTENSION_HDR Device-specific extension implementation for enhancing the dynamic range of the final image.
int EXTENSION_NIGHT Device-specific extension implementation that aims to suppress noise and improve the overall image quality under low light conditions.
Public methods
T get(int extension, Key key) Gets an extension specific camera characteristics field value.
Set<CaptureRequest.Key> getAvailableCaptureRequestKeys(int extension) Returns the set of keys supported by a CaptureRequest submitted in aCameraExtensionSession with a given extension type.
Set<CaptureResult.Key> getAvailableCaptureResultKeys(int extension) Returns the set of keys supported by a CaptureResult passed as an argument toCameraExtensionSession.ExtensionCaptureCallback.onCaptureResultAvailable.
Range<Long> getEstimatedCaptureLatencyRangeMillis(int extension, Size captureOutputSize, int format) Returns the estimated capture latency range in milliseconds for the target capture resolution during the calls to CameraExtensionSession.capture.
List<Size> getExtensionSupportedSizes(int extension, int format) 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.
List<Size> getExtensionSupportedSizes(int extension, Class klass) Get a list of sizes compatible with klass to use as an output for the repeating requestCameraExtensionSession.setRepeatingRequest.
Set<CameraCharacteristics.Key> getKeys(int extension) Returns the CameraCharacteristics keys that have extension-specific values.
List<Size> getPostviewSupportedSizes(int extension, Size captureSize, int format) 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.
List<Integer> getSupportedExtensions() Return a list of supported device-specific extensions for a given camera device.
boolean isCaptureProcessProgressAvailable(int extension) Retrieve support for capture progress callbacks viaCameraExtensionSession.ExtensionCaptureCallback.onCaptureProcessProgressed.
boolean isExtensionSupported(int extensionType) Checks if a given camera extension is available for a specific camera device.
boolean isPostviewAvailable(int extension) Checks for postview support of still capture.
Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. finalClass<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

EXTENSION_AUTOMATIC

public static final int EXTENSION_AUTOMATIC

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

Constant Value: 0 (0x00000000)

EXTENSION_BEAUTY

public static final int EXTENSION_BEAUTY

This constant was deprecated in API level 33.
Use [EXTENSION_FACE_RETOUCH](/reference/android/hardware/camera2/CameraExtensionCharacteristics#EXTENSION%5FFACE%5FRETOUCH) instead.

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

Constant Value: 1 (0x00000001)

EXTENSION_BOKEH

public static final int EXTENSION_BOKEH

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

Constant Value: 2 (0x00000002)

EXTENSION_FACE_RETOUCH

public static final int EXTENSION_FACE_RETOUCH

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

Constant Value: 1 (0x00000001)

EXTENSION_HDR

public static final int EXTENSION_HDR

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

Constant Value: 3 (0x00000003)

EXTENSION_NIGHT

public static final int EXTENSION_NIGHT

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

Constant Value: 4 (0x00000004)

Public methods

get

public T get (int extension, Key key)

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\u2019s 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 the following: EXTENSION_AUTOMATIC EXTENSION_FACE_RETOUCH EXTENSION_BOKEH EXTENSION_HDR EXTENSION_NIGHT
key Key: The characteristics field to read. This value cannot be null.
Returns
T The value of that key, or null if the field is not set.
Throws
IllegalArgumentException if the key is not valid or extension type is not a supported device-specific extension.

getExtensionSupportedSizes

public List<Size> getExtensionSupportedSizes (int extension, int format)

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](/reference/android/hardware/camera2/CameraExtensionSession#capture%28android.hardware.camera2.CaptureRequest,%20java.util.concurrent.Executor,%20android.hardware.camera2.CameraExtensionSession.ExtensionCaptureCallback%29).

Note that device-specific extensions are allowed to support only a subset of the camera resolutions advertised by[StreamConfigurationMap.getOutputSizes](/reference/android/hardware/camera2/params/StreamConfigurationMap#getOutputSizes%28int%29).

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, ImageFormat.YCBCR_P010 or ImageFormat.DEPTH_JPEG may or may not be supported.

Parameters
extension int: the extension type. Value is either 0 or a combination of the following: EXTENSION_AUTOMATIC EXTENSION_FACE_RETOUCH EXTENSION_BOKEH EXTENSION_HDR EXTENSION_NIGHT
format int: device-specific extension output format
Returns
List<Size> non-modifiable list of available sizes or an empty list if the format is not supported. This value cannot be null.
Throws
IllegalArgumentException in case of format different from ImageFormat.JPEG, ImageFormat.YUV_420_888, ImageFormat.JPEG_R, ImageFormat.DEPTH_JPEG, ImageFormat.YCBCR_P010; or unsupported extension.

getPostviewSupportedSizes

public List<Size> getPostviewSupportedSizes (int extension, Size captureSize, int format)

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[StreamConfigurationMap.getOutputSizes](/reference/android/hardware/camera2/params/StreamConfigurationMap#getOutputSizes%28int%29).

Parameters
extension int: the extension type. Value is either 0 or a combination of the following: EXTENSION_AUTOMATIC EXTENSION_FACE_RETOUCH EXTENSION_BOKEH EXTENSION_HDR EXTENSION_NIGHT
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
Returns
List<Size> non-modifiable list of available sizes or an empty list if the format and size is not supported. This value cannot be null.
Throws
IllegalArgumentException in case of unsupported extension or if postview feature is not supported by extension.

isExtensionSupported

public boolean isExtensionSupported (int extensionType)

Checks if a given camera extension is available for a specific camera device.

An extension may not be available on all devices. Even if a device supports extensions in general, a specific extension might not be implemented for a particular camera ID.

In contrast to [getSupportedExtensions()](/reference/android/hardware/camera2/CameraExtensionCharacteristics#getSupportedExtensions%28%29) this method can also be used to query the available device specific extension modes.

Parameters
extensionType int: The camera extension to query for. Value is either 0 or a combination of the following: EXTENSION_AUTOMATIC EXTENSION_FACE_RETOUCH EXTENSION_BOKEH EXTENSION_HDR EXTENSION_NIGHT
Returns
boolean true if the specified extension is supported for the given camera device,false otherwise.