diff --git a/api/current.txt b/api/current.txt index 007f2e778cffe..457a7d9d2417d 100644 --- a/api/current.txt +++ b/api/current.txt @@ -13806,6 +13806,7 @@ package android.hardware.camera2 { field public static final int HOT_PIXEL_MODE_FAST = 1; // 0x1 field public static final int HOT_PIXEL_MODE_HIGH_QUALITY = 2; // 0x2 field public static final int HOT_PIXEL_MODE_OFF = 0; // 0x0 + field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_3 = 3; // 0x3 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_FULL = 1; // 0x1 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY = 2; // 0x2 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED = 0; // 0x0 diff --git a/api/system-current.txt b/api/system-current.txt index 56323b6aacf59..d29721a369db5 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -14175,6 +14175,7 @@ package android.hardware.camera2 { field public static final int HOT_PIXEL_MODE_FAST = 1; // 0x1 field public static final int HOT_PIXEL_MODE_HIGH_QUALITY = 2; // 0x2 field public static final int HOT_PIXEL_MODE_OFF = 0; // 0x0 + field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_3 = 3; // 0x3 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_FULL = 1; // 0x1 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY = 2; // 0x2 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED = 0; // 0x0 diff --git a/api/test-current.txt b/api/test-current.txt index 63c64e820d046..779b831973ec0 100644 --- a/api/test-current.txt +++ b/api/test-current.txt @@ -13814,6 +13814,7 @@ package android.hardware.camera2 { field public static final int HOT_PIXEL_MODE_FAST = 1; // 0x1 field public static final int HOT_PIXEL_MODE_HIGH_QUALITY = 2; // 0x2 field public static final int HOT_PIXEL_MODE_OFF = 0; // 0x0 + field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_3 = 3; // 0x3 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_FULL = 1; // 0x1 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY = 2; // 0x2 field public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED = 0; // 0x0 diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index bb0a04f62d043..e84427394172d 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -2767,22 +2767,39 @@ public final class CameraCharacteristics extends CameraMetadataGenerally classifies the overall set of the camera device functionality.

- *

Camera devices will come in three flavors: LEGACY, LIMITED and FULL.

- *

A FULL device will support below capabilities:

+ *

The supported hardware level is a high-level description of the camera device's + * capabilities, summarizing several capabilities into one field. Each level adds additional + * features to the previous one, and is always a strict superset of the previous level. + * The ordering is LEGACY < LIMITED < FULL < LEVEL_3.

+ *

Starting from LEVEL_3, the level enumerations are guaranteed to be in increasing + * numerical value as well. To check if a given device is at least at a given hardware level, + * the following code snippet can be used:

+ * 
// Returns true if the device supports the required hardware level, or better.
+     * boolean isHardwareLevelSupported(CameraCharacteristics c, int requiredLevel) {
+     *     int deviceLevel = c.get(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL);
+     *     if (deviceLevel == CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY) {
+     *         return requiredLevel == deviceLevel;
+     *     }
+     *     // deviceLevel is not LEGACY, can use numerical sort
+     *     return requiredLevel <= deviceLevel;
+     * }
+     *
+ *

At a high level, the levels are:

* - *

A LIMITED device may have some or none of the above characteristics. - * To find out more refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.

+ *

See the individual level enums for full descriptions of the supported capabilities. The + * {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} entry describes the device's capabilities at a + * finer-grain level, if needed. In addition, many controls have their available settings or + * ranges defined in individual {@link android.hardware.camera2.CameraCharacteristics } entries.

*

Some features are not part of any particular hardware level or capability and must be * queried separately. These include:

* - *

A LEGACY device does not support per-frame control, manual sensor control, manual - * post-processing, arbitrary cropping regions, and has relaxed performance constraints.

- *

Each higher level supports everything the lower level supports - * in this order: FULL > LIMITED > LEGACY.

- *

Note: - * Pre-API level 23, FULL devices also supported arbitrary cropping region - * ({@link CameraCharacteristics#SCALER_CROPPING_TYPE android.scaler.croppingType} == FREEFORM); this requirement was relaxed in API level 23, - * and FULL devices may only support CENTERED cropping.

*

Possible values: *

*

This key is available on all devices.

* @@ -2813,16 +2823,12 @@ public final class CameraCharacteristics extends CameraMetadata INFO_SUPPORTED_HARDWARE_LEVEL = diff --git a/core/java/android/hardware/camera2/CameraDevice.java b/core/java/android/hardware/camera2/CameraDevice.java index 852a4d9fd0159..5d52498bb6d87 100644 --- a/core/java/android/hardware/camera2/CameraDevice.java +++ b/core/java/android/hardware/camera2/CameraDevice.java @@ -314,7 +314,7 @@ public abstract class CameraDevice implements AutoCloseable { *
*

* - *

Limited-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + *

Limited-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices * support at least the following stream combinations in addition to those for * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: @@ -332,13 +332,13 @@ public abstract class CameraDevice implements AutoCloseable { *
*

* - *

FULL-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + *

FULL-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices * support at least the following stream combinations in addition to those for * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: * * - * + * * * * @@ -389,6 +389,22 @@ public abstract class CameraDevice implements AutoCloseable { *
FULL-capability additional guaranteed configurations
FULL-level additional guaranteed configurations
Target 1Target 2Target 3 Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax size
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code MAXIMUM} Maximum-resolution GPU processing with preview.

*

* + *

LEVEL-3 ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL_3}) + * support at least the following stream combinations in addition to the combinations for + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and for + * RAW capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes + * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}): + * + * + * + * + * + * + * + *
LEVEL-3 additional guaranteed configurations
Target 1Target 2Target 3Target 4Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax sizeTypeMax size
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code 640x480} {@code YUV}{@code MAXIMUM} {@code RAW}{@code MAXIMUM} In-app viewfinder analysis with dynamic selection of output format.
{@code PRIV}{@code PREVIEW} {@code PRIV}{@code 640x480} {@code JPEG}{@code MAXIMUM} {@code RAW}{@code MAXIMUM} In-app viewfinder analysis with dynamic selection of output format.

+ *

+ * *

Since the capabilities of camera devices vary greatly, a given camera device may support * target combinations with sizes outside of these guarantees, but this can only be tested for * by attempting to create a session with such targets.

@@ -503,7 +519,7 @@ public abstract class CameraDevice implements AutoCloseable { * #rb { border-right-width: thick; } * * - *

Limited-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + *

LIMITED-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices * support at least the following stream combinations for creating a reprocessable capture * session in addition to those listed in {@link #createCaptureSession createCaptureSession} for @@ -520,14 +536,14 @@ public abstract class CameraDevice implements AutoCloseable { *
*

* - *

FULL-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + *

FULL-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices * support at least the following stream combinations for creating a reprocessable capture * session in addition to those for * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: * * - * + * * * * @@ -557,6 +573,22 @@ public abstract class CameraDevice implements AutoCloseable { *
FULL-capability additional guaranteed configurations for creating a reprocessable capture session
({@code PRIV} input is guaranteed only if PRIVATE reprocessing is supported. {@code YUV} input is guaranteed only if YUV reprocessing is supported)
FULL-level additional guaranteed configurations for creating a reprocessable capture session
({@code PRIV} input is guaranteed only if PRIVATE reprocessing is supported. {@code YUV} input is guaranteed only if YUV reprocessing is supported)
InputTarget 1Target 2Target 3Target 4Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax sizeTypeMax sizeTypeMax size
{@code YUV}{@code MAXIMUM} {@code YUV}{@code MAXIMUM} {@code PRIV}{@code PREVIEW} Maximum-resolution multi-frame image fusion in-app processing with regular preview.

*

* + *

LEVEL-3 ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} + * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL_3}) devices + * support at least the following stream combinations for creating a reprocessable capture + * session in addition to those for + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} devices. Note that targets in the "Reprocess-only target" column may only be + * used as an output target for a reprocess capture request, not as an output to a regular capture request. + * + * + * + * + * + * + * + *
LEVEL-3 additional guaranteed configurations for creating a reprocessable capture session
({@code PRIV} input is guaranteed only if PRIVATE reprocessing is supported. {@code YUV} input is always guaranteed.
InputTarget 1Target 2Target 3Target 4Reprocess-only targetSample use case(s)
TypeMax sizeTypeMax sizeTypeMax sizeTypeMax sizeTypeMax sizeTypeMax size
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code PRIV}{@code 640x480} {@code RAW}{@code MAXIMUM} In-app viewfinder analysis with ZSL and RAW.
{@code PRIV}/{@code YUV}{@code MAXIMUM} Same as input{@code MAXIMUM} {@code PRIV}{@code PREVIEW} {@code PRIV}{@code 640x480} {@code RAW}{@code MAXIMUM} {@code JPEG}{@code MAXIMUM}In-app viewfinder analysis with ZSL, RAW, and JPEG reprocessing output.

+ *

+ * * @param inputConfig The configuration for the input {@link Surface} * @param outputs The new set of Surfaces that should be made available as * targets for captured image data. diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index f61892ec61143..d58ad22396c67 100644 --- a/core/java/android/hardware/camera2/CameraMetadata.java +++ b/core/java/android/hardware/camera2/CameraMetadata.java @@ -964,23 +964,102 @@ public abstract class CameraMetadata { // /** - *

This camera device has only limited capabilities.

+ *

This camera device does not have enough capabilities to qualify as a FULL device or + * better.

+ *

Only the stream configurations listed in the LEGACY and LIMITED tables in the + * {@link android.hardware.camera2.CameraDevice#createCaptureSession createCaptureSession} documentation are guaranteed to be supported.

+ *

All LIMITED devices support the BACKWARDS_COMPATIBLE capability, indicating basic + * support for color image capture. The only exception is that the device may + * alternatively support only the DEPTH_OUTPUT capability, if it can only output depth + * measurements and not color images.

+ *

LIMITED devices and above require the use of {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} + * to lock exposure metering (and calculate flash power, for cameras with flash) before + * capturing a high-quality still image.

+ *

A LIMITED device that only lists the BACKWARDS_COMPATIBLE capability is only + * required to support full-automatic operation and post-processing (OFF is not + * supported for {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode}, {@link CaptureRequest#CONTROL_AF_MODE android.control.afMode}, or + * {@link CaptureRequest#CONTROL_AWB_MODE android.control.awbMode})

+ *

Additional capabilities may optionally be supported by a LIMITED-level device, and + * can be checked for in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.

+ * + * @see CaptureRequest#CONTROL_AE_MODE + * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER + * @see CaptureRequest#CONTROL_AF_MODE + * @see CaptureRequest#CONTROL_AWB_MODE + * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED = 0; /** *

This camera device is capable of supporting advanced imaging applications.

+ *

The stream configurations listed in the FULL, LEGACY and LIMITED tables in the + * {@link android.hardware.camera2.CameraDevice#createCaptureSession createCaptureSession} documentation are guaranteed to be supported.

+ *

A FULL device will support below capabilities:

+ *
    + *
  • BURST_CAPTURE capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} contains + * BURST_CAPTURE)
    • + *
  • Per frame control ({@link CameraCharacteristics#SYNC_MAX_LATENCY android.sync.maxLatency} == PER_FRAME_CONTROL)
    • + *
  • Manual sensor control ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} contains MANUAL_SENSOR)
    • + *
  • Manual post-processing control ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} contains + * MANUAL_POST_PROCESSING)
    • + *
  • The required exposure time range defined in {@link CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE android.sensor.info.exposureTimeRange}
    • + *
  • The required maxFrameDuration defined in {@link CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION android.sensor.info.maxFrameDuration}
    • + *
+ *

Note: + * Pre-API level 23, FULL devices also supported arbitrary cropping region + * ({@link CameraCharacteristics#SCALER_CROPPING_TYPE android.scaler.croppingType} == FREEFORM); this requirement was relaxed in API level + * 23, and FULL devices may only support CENTERED cropping.

+ * + * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES + * @see CameraCharacteristics#SCALER_CROPPING_TYPE + * @see CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE + * @see CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION + * @see CameraCharacteristics#SYNC_MAX_LATENCY * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ public static final int INFO_SUPPORTED_HARDWARE_LEVEL_FULL = 1; /** *

This camera device is running in backward compatibility mode.

+ *

Only the stream configurations listed in the LEGACY table in the {@link android.hardware.camera2.CameraDevice#createCaptureSession createCaptureSession} + * documentation are supported.

+ *

A LEGACY device does not support per-frame control, manual sensor control, manual + * post-processing, arbitrary cropping regions, and has relaxed performance constraints. + * No additional capabilities beyond BACKWARD_COMPATIBLE will ever be listed by a + * LEGACY device in {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities}.

+ *

In addition, the {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is not functional on LEGACY + * devices. Instead, every request that includes a JPEG-format output target is treated + * as triggering a still capture, internally executing a precapture trigger. This may + * fire the flash for flash power metering during precapture, and then fire the flash + * for the final capture, if a flash is available on the device and the AE mode is set to + * enable the flash.

+ * + * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER + * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ public static final int INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY = 2; + /** + *

This camera device is capable of YUV reprocessing and RAW data capture, in addition to + * FULL-level capabilities.

+ *

The stream configurations listed in the LEVEL_3, RAW, FULL, LEGACY and + * LIMITED tables in the {@link android.hardware.camera2.CameraDevice#createCaptureSession createCaptureSession} + * documentation are guaranteed to be supported.

+ *

The following additional capabilities are guaranteed to be supported:

+ *
    + *
  • YUV_REPROCESSING capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} contains + * YUV_REPROCESSING)
    • + *
  • RAW capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES android.request.availableCapabilities} contains + * RAW)
    • + *
+ * + * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL + */ + public static final int INFO_SUPPORTED_HARDWARE_LEVEL_3 = 3; + // // Enumeration values for CameraCharacteristics#SYNC_MAX_LATENCY //