From c925656a1ee1619a369116a4e8d415fa3bca441f Mon Sep 17 00:00:00 2001 From: Yin-Chia Yeh Date: Fri, 15 Jun 2018 15:37:08 -0700 Subject: Camera: codegen doc update Test: N/A. Doc update Bug: 109666939 Bug: 113052379 Change-Id: I2bd176a7f5ada755c8a79201d142a98131e2e82c Merged-In: I2bd176a7f5ada755c8a79201d142a98131e2e82c (cherry picked from commit 6c73e409fccf4b2e1b4a5f4bac2eea1c07480e16) --- .../hardware/camera2/CameraCharacteristics.java | 22 ++- .../android/hardware/camera2/CaptureRequest.java | 144 +++++++++++++---- .../android/hardware/camera2/CaptureResult.java | 170 ++++++++++++++++----- 3 files changed, 263 insertions(+), 73 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index c3a57070c440..6ce2780c569b 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -2371,13 +2371,25 @@ public final class CameraCharacteristics extends CameraMetadata(0, 0) being the top-left of this rectangle.

*

The active array may be smaller than the full pixel array, since the full array may - * include black calibration pixels or other inactive regions, and geometric correction - * resulting in scaling or cropping may have been applied.

+ * include black calibration pixels or other inactive regions.

+ *

For devices that do not support {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the active + * array must be the same as {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.

+ *

For devices that support {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the active array must + * be enclosed by {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}. The difference between + * pre-correction active array and active array accounts for scaling or cropping caused + * by lens geometric distortion correction.

+ *

In general, application should always refer to active array size for controls like + * metering regions or crop region. Two exceptions are when the application is dealing with + * RAW image buffers (RAW_SENSOR, RAW10, RAW12 etc), or when application explicitly set + * {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} to OFF. In these cases, application should refer + * to {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.

*

Units: Pixel coordinates on the image sensor

*

This key is available on all devices.

* + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CaptureRequest#SCALER_CROP_REGION * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key SENSOR_INFO_ACTIVE_ARRAY_SIZE = @@ -2622,9 +2634,9 @@ public final class CameraCharacteristics extends CameraMetadata *
  • {@link CameraCharacteristics#LENS_DISTORTION android.lens.distortion}.
    • * - *

    If all of the geometric distortion fields are no-ops, this rectangle will be the same - * as the post-distortion-corrected rectangle given in - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.

    + *

    If the camera device doesn't support geometric distortion correction, or all of the + * geometric distortion fields are no-ops, this rectangle will be the same as the + * post-distortion-corrected rectangle given in {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.

    *

    This rectangle is defined relative to the full pixel array; (0,0) is the top-left of * the full pixel array, and the size of the full pixel array is given by * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.

    diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index ec51ba56c571..0b92b0cbef15 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -1277,11 +1277,26 @@ public final class CaptureRequest extends CameraMetadata> * Otherwise will always be present.

    *

    The maximum number of regions supported by the device is determined by the value * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe}.

    - *

    The coordinate system is based on the active pixel array, - * with (0,0) being the top-left pixel in the active pixel array, and + *

    For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0,0) being + * the top-left pixel in the active pixel array, and * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the - * bottom-right pixel in the active pixel array.

    + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

    + *

    For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.height - 1) being the bottom-right + * pixel in the pre-correction active pixel array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + * (0, 0) being the top-left pixel of the active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

    *

    The weight must be within [0, 1000], and represents a weight * for every pixel in the area. This means that a large metering area * with the same weight as a smaller area will have more effect in @@ -1297,15 +1312,20 @@ public final class CaptureRequest extends CameraMetadata> * region and output only the intersection rectangle as the metering region in the result * metadata. If the region is entirely outside the crop region, it will be ignored and * not reported in the result metadata.

    - *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} depending on + * distortion correction capability and mode

    *

    Range of valid values:
    * Coordinates must be between [(0,0), (width, height)) of - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} + * depending on distortion correction capability and mode

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AE + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CaptureRequest#SCALER_CROP_REGION * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key CONTROL_AE_REGIONS = @@ -1451,11 +1471,26 @@ public final class CaptureRequest extends CameraMetadata> * Otherwise will always be present.

    *

    The maximum number of focus areas supported by the device is determined by the value * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf}.

    - *

    The coordinate system is based on the active pixel array, - * with (0,0) being the top-left pixel in the active pixel array, and + *

    For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0,0) being + * the top-left pixel in the active pixel array, and + * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

    + *

    For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.height - 1) being the bottom-right + * pixel in the pre-correction active pixel array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + * (0, 0) being the top-left pixel of the active array, and * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the - * bottom-right pixel in the active pixel array.

    + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

    *

    The weight must be within [0, 1000], and represents a weight * for every pixel in the area. This means that a large metering area * with the same weight as a smaller area will have more effect in @@ -1472,15 +1507,20 @@ public final class CaptureRequest extends CameraMetadata> * region and output only the intersection rectangle as the metering region in the result * metadata. If the region is entirely outside the crop region, it will be ignored and * not reported in the result metadata.

    - *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} depending on + * distortion correction capability and mode

    *

    Range of valid values:
    * Coordinates must be between [(0,0), (width, height)) of - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} + * depending on distortion correction capability and mode

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AF + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CaptureRequest#SCALER_CROP_REGION * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key CONTROL_AF_REGIONS = @@ -1620,11 +1660,26 @@ public final class CaptureRequest extends CameraMetadata> * Otherwise will always be present.

    *

    The maximum number of regions supported by the device is determined by the value * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb}.

    - *

    The coordinate system is based on the active pixel array, - * with (0,0) being the top-left pixel in the active pixel array, and + *

    For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0,0) being + * the top-left pixel in the active pixel array, and * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the - * bottom-right pixel in the active pixel array.

    + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

    + *

    For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.height - 1) being the bottom-right + * pixel in the pre-correction active pixel array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + * (0, 0) being the top-left pixel of the active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

    *

    The weight must range from 0 to 1000, and represents a weight * for every pixel in the area. This means that a large metering area * with the same weight as a smaller area will have more effect in @@ -1640,15 +1695,20 @@ public final class CaptureRequest extends CameraMetadata> * region and output only the intersection rectangle as the metering region in the result * metadata. If the region is entirely outside the crop region, it will be ignored and * not reported in the result metadata.

    - *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + *

    Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} depending on + * distortion correction capability and mode

    *

    Range of valid values:
    * Coordinates must be between [(0,0), (width, height)) of - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} + * depending on distortion correction capability and mode

    *

    Optional - This value may be {@code null} on some devices.

    * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AWB + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CaptureRequest#SCALER_CROP_REGION * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key CONTROL_AWB_REGIONS = @@ -2441,9 +2501,17 @@ public final class CaptureRequest extends CameraMetadata> /** *

    The desired region of the sensor to read out for this capture.

    *

    This control can be used to implement digital zoom.

    - *

    The crop region coordinate system is based off - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0, 0) being the - * top-left corner of the sensor active array.

    + *

    For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0, 0) being + * the top-left pixel of the active array.

    + *

    For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + * (0, 0) being the top-left pixel of the active array.

    *

    Output streams use this rectangle to produce their output, * cropping to a smaller region if necessary to maintain the * stream's aspect ratio, then scaling the sensor input to @@ -2462,20 +2530,30 @@ public final class CaptureRequest extends CameraMetadata> * outputs will crop horizontally (pillarbox), and 16:9 * streams will match exactly. These additional crops will * be centered within the crop region.

    - *

    The width and height of the crop region cannot - * be set to be smaller than + *

    If the coordinate system is android.sensor.info.activeArraysSize, the width and height + * of the crop region cannot be set to be smaller than * floor( activeArraySize.width / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and * floor( activeArraySize.height / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ), respectively.

    + *

    If the coordinate system is {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, the width + * and height of the crop region cannot be set to be smaller than + * floor( preCorrectionActiveArraySize.width / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) + * and + * floor( preCorrectionActiveArraySize.height / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ), + * respectively.

    *

    The camera device may adjust the crop region to account * for rounding and other hardware requirements; the final * crop region used will be included in the output capture * result.

    *

    Units: Pixel coordinates relative to - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

    + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} depending on distortion correction + * capability and mode

    *

    This key is available on all devices.

    * + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key SCALER_CROP_REGION = @@ -3194,15 +3272,14 @@ public final class CaptureRequest extends CameraMetadata> * any correction at all would slow down capture rate. Every output stream will have a * similar amount of enhancement applied.

    *

    The correction only applies to processed outputs such as YUV, JPEG, or DEPTH16; it is not - * applied to any RAW output. Metadata coordinates such as face rectangles or metering + * applied to any RAW output. Metadata coordinates such as face rectangles or metering * regions are also not affected by correction.

    - *

    Applications enabling distortion correction need to pay extra attention when converting - * image coordinates between corrected output buffers and the sensor array. For example, if - * the app supports tap-to-focus and enables correction, it then has to apply the distortion - * model described in {@link CameraCharacteristics#LENS_DISTORTION android.lens.distortion} to the image buffer tap coordinates to properly - * calculate the tap position on the sensor active array to be used with - * {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions}. The same applies in reverse to detected face rectangles if - * they need to be drawn on top of the corrected output buffers.

    + *

    This control will be on by default on devices that support this control. Applications + * disabling distortion correction need to pay extra attention with the coordinate system of + * metering regions, crop region, and face rectangles. When distortion correction is OFF, + * metadata coordinates follow the coordinate system of + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}. When distortion is not OFF, metadata + * coordinates follow the coordinate system of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.

    *

    Possible values: *

      *
    • {@link #DISTORTION_CORRECTION_MODE_OFF OFF}
      • @@ -3213,9 +3290,10 @@ public final class CaptureRequest extends CameraMetadata> * {@link CameraCharacteristics#DISTORTION_CORRECTION_AVAILABLE_MODES android.distortionCorrection.availableModes}

      *

      Optional - This value may be {@code null} on some devices.

      * - * @see CaptureRequest#CONTROL_AF_REGIONS * @see CameraCharacteristics#DISTORTION_CORRECTION_AVAILABLE_MODES * @see CameraCharacteristics#LENS_DISTORTION + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE * @see #DISTORTION_CORRECTION_MODE_OFF * @see #DISTORTION_CORRECTION_MODE_FAST * @see #DISTORTION_CORRECTION_MODE_HIGH_QUALITY diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index a49064f8fb71..e007d282ad04 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -736,11 +736,26 @@ public class CaptureResult extends CameraMetadata> { * Otherwise will always be present.

      *

      The maximum number of regions supported by the device is determined by the value * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AE android.control.maxRegionsAe}.

      - *

      The coordinate system is based on the active pixel array, - * with (0,0) being the top-left pixel in the active pixel array, and + *

      For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0,0) being + * the top-left pixel in the active pixel array, and * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the - * bottom-right pixel in the active pixel array.

      + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

      + *

      For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.height - 1) being the bottom-right + * pixel in the pre-correction active pixel array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + * (0, 0) being the top-left pixel of the active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

      *

      The weight must be within [0, 1000], and represents a weight * for every pixel in the area. This means that a large metering area * with the same weight as a smaller area will have more effect in @@ -756,15 +771,20 @@ public class CaptureResult extends CameraMetadata> { * region and output only the intersection rectangle as the metering region in the result * metadata. If the region is entirely outside the crop region, it will be ignored and * not reported in the result metadata.

      - *

      Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

      + *

      Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} depending on + * distortion correction capability and mode

      *

      Range of valid values:
      * Coordinates must be between [(0,0), (width, height)) of - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

      + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} + * depending on distortion correction capability and mode

      *

      Optional - This value may be {@code null} on some devices.

      * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AE + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CaptureRequest#SCALER_CROP_REGION * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key CONTROL_AE_REGIONS = @@ -1158,11 +1178,26 @@ public class CaptureResult extends CameraMetadata> { * Otherwise will always be present.

      *

      The maximum number of focus areas supported by the device is determined by the value * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AF android.control.maxRegionsAf}.

      - *

      The coordinate system is based on the active pixel array, - * with (0,0) being the top-left pixel in the active pixel array, and + *

      For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0,0) being + * the top-left pixel in the active pixel array, and + * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

      + *

      For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.height - 1) being the bottom-right + * pixel in the pre-correction active pixel array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + * (0, 0) being the top-left pixel of the active array, and * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the - * bottom-right pixel in the active pixel array.

      + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

      *

      The weight must be within [0, 1000], and represents a weight * for every pixel in the area. This means that a large metering area * with the same weight as a smaller area will have more effect in @@ -1179,15 +1214,20 @@ public class CaptureResult extends CameraMetadata> { * region and output only the intersection rectangle as the metering region in the result * metadata. If the region is entirely outside the crop region, it will be ignored and * not reported in the result metadata.

      - *

      Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

      + *

      Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} depending on + * distortion correction capability and mode

      *

      Range of valid values:
      * Coordinates must be between [(0,0), (width, height)) of - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

      + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} + * depending on distortion correction capability and mode

      *

      Optional - This value may be {@code null} on some devices.

      * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AF + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CaptureRequest#SCALER_CROP_REGION * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key CONTROL_AF_REGIONS = @@ -1736,11 +1776,26 @@ public class CaptureResult extends CameraMetadata> { * Otherwise will always be present.

      *

      The maximum number of regions supported by the device is determined by the value * of {@link CameraCharacteristics#CONTROL_MAX_REGIONS_AWB android.control.maxRegionsAwb}.

      - *

      The coordinate system is based on the active pixel array, - * with (0,0) being the top-left pixel in the active pixel array, and + *

      For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0,0) being + * the top-left pixel in the active pixel array, and + * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

      + *

      For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array, and + * ({@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.width - 1, + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}.height - 1) being the bottom-right + * pixel in the pre-correction active pixel array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + * (0, 0) being the top-left pixel of the active array, and * ({@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.width - 1, - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the - * bottom-right pixel in the active pixel array.

      + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.height - 1) being the bottom-right pixel in the + * active pixel array.

      *

      The weight must range from 0 to 1000, and represents a weight * for every pixel in the area. This means that a large metering area * with the same weight as a smaller area will have more effect in @@ -1756,15 +1811,20 @@ public class CaptureResult extends CameraMetadata> { * region and output only the intersection rectangle as the metering region in the result * metadata. If the region is entirely outside the crop region, it will be ignored and * not reported in the result metadata.

      - *

      Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

      + *

      Units: Pixel coordinates within {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} depending on + * distortion correction capability and mode

      *

      Range of valid values:
      * Coordinates must be between [(0,0), (width, height)) of - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

      + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} + * depending on distortion correction capability and mode

      *

      Optional - This value may be {@code null} on some devices.

      * * @see CameraCharacteristics#CONTROL_MAX_REGIONS_AWB + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CaptureRequest#SCALER_CROP_REGION * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key CONTROL_AWB_REGIONS = @@ -3105,9 +3165,17 @@ public class CaptureResult extends CameraMetadata> { /** *

      The desired region of the sensor to read out for this capture.

      *

      This control can be used to implement digital zoom.

      - *

      The crop region coordinate system is based off - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0, 0) being the - * top-left corner of the sensor active array.

      + *

      For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0, 0) being + * the top-left pixel of the active array.

      + *

      For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + * (0, 0) being the top-left pixel of the active array.

      *

      Output streams use this rectangle to produce their output, * cropping to a smaller region if necessary to maintain the * stream's aspect ratio, then scaling the sensor input to @@ -3126,20 +3194,30 @@ public class CaptureResult extends CameraMetadata> { * outputs will crop horizontally (pillarbox), and 16:9 * streams will match exactly. These additional crops will * be centered within the crop region.

      - *

      The width and height of the crop region cannot - * be set to be smaller than + *

      If the coordinate system is android.sensor.info.activeArraysSize, the width and height + * of the crop region cannot be set to be smaller than * floor( activeArraySize.width / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) and * floor( activeArraySize.height / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ), respectively.

      + *

      If the coordinate system is {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, the width + * and height of the crop region cannot be set to be smaller than + * floor( preCorrectionActiveArraySize.width / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ) + * and + * floor( preCorrectionActiveArraySize.height / {@link CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM android.scaler.availableMaxDigitalZoom} ), + * respectively.

      *

      The camera device may adjust the crop region to account * for rounding and other hardware requirements; the final * crop region used will be included in the output capture * result.

      *

      Units: Pixel coordinates relative to - * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}

      + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} depending on distortion correction + * capability and mode

      *

      This key is available on all devices.

      * + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key SCALER_CROP_REGION = @@ -3630,12 +3708,23 @@ public class CaptureResult extends CameraMetadata> { /** *

      List of landmarks for detected * faces.

      - *

      The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + *

      For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0, 0) being + * the top-left pixel of the active array.

      + *

      For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with * (0, 0) being the top-left pixel of the active array.

      *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} == FULL * This key is available on all devices.

      * + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide */ @@ -3645,12 +3734,23 @@ public class CaptureResult extends CameraMetadata> { /** *

      List of the bounding rectangles for detected * faces.

      - *

      The coordinate system is that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with + *

      For devices not supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system always follows that of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with (0, 0) being + * the top-left pixel of the active array.

      + *

      For devices supporting {@link CaptureRequest#DISTORTION_CORRECTION_MODE android.distortionCorrection.mode} control, the coordinate + * system depends on the mode being set. + * When the distortion correction mode is OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}, with + * (0, 0) being the top-left pixel of the pre-correction active array. + * When the distortion correction mode is not OFF, the coordinate system follows + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, with * (0, 0) being the top-left pixel of the active array.

      *

      Only available if {@link CaptureRequest#STATISTICS_FACE_DETECT_MODE android.statistics.faceDetectMode} != OFF * This key is available on all devices.

      * + * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE * @see CaptureRequest#STATISTICS_FACE_DETECT_MODE * @hide */ @@ -4484,15 +4584,14 @@ public class CaptureResult extends CameraMetadata> { * any correction at all would slow down capture rate. Every output stream will have a * similar amount of enhancement applied.

      *

      The correction only applies to processed outputs such as YUV, JPEG, or DEPTH16; it is not - * applied to any RAW output. Metadata coordinates such as face rectangles or metering + * applied to any RAW output. Metadata coordinates such as face rectangles or metering * regions are also not affected by correction.

      - *

      Applications enabling distortion correction need to pay extra attention when converting - * image coordinates between corrected output buffers and the sensor array. For example, if - * the app supports tap-to-focus and enables correction, it then has to apply the distortion - * model described in {@link CameraCharacteristics#LENS_DISTORTION android.lens.distortion} to the image buffer tap coordinates to properly - * calculate the tap position on the sensor active array to be used with - * {@link CaptureRequest#CONTROL_AF_REGIONS android.control.afRegions}. The same applies in reverse to detected face rectangles if - * they need to be drawn on top of the corrected output buffers.

      + *

      This control will be on by default on devices that support this control. Applications + * disabling distortion correction need to pay extra attention with the coordinate system of + * metering regions, crop region, and face rectangles. When distortion correction is OFF, + * metadata coordinates follow the coordinate system of + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize}. When distortion is not OFF, metadata + * coordinates follow the coordinate system of {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.

      *

      Possible values: *

        *
      • {@link #DISTORTION_CORRECTION_MODE_OFF OFF}
        • @@ -4503,9 +4602,10 @@ public class CaptureResult extends CameraMetadata> { * {@link CameraCharacteristics#DISTORTION_CORRECTION_AVAILABLE_MODES android.distortionCorrection.availableModes}

        *

        Optional - This value may be {@code null} on some devices.

        * - * @see CaptureRequest#CONTROL_AF_REGIONS * @see CameraCharacteristics#DISTORTION_CORRECTION_AVAILABLE_MODES * @see CameraCharacteristics#LENS_DISTORTION + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE * @see #DISTORTION_CORRECTION_MODE_OFF * @see #DISTORTION_CORRECTION_MODE_FAST * @see #DISTORTION_CORRECTION_MODE_HIGH_QUALITY -- cgit v1.2.3-59-g8ed1b From a8cfb0ae932be1b34894db6ded8a76bd67ca1269 Mon Sep 17 00:00:00 2001 From: Yin-Chia Yeh Date: Fri, 13 Jul 2018 13:42:43 -0700 Subject: Camera: hardware level related doc update Codegen doc update + CameraDevice manual update about EXTERNAL hardware level. Test: check offline-sdk-docs output Bug: 77861412 Bug: 113052379 Change-Id: I70c87a176cf873cf8bec2037f973a94fe99aef2e Merged-In: I70c87a176cf873cf8bec2037f973a94fe99aef2e (cherry picked from commit c565700b94bc5f1fe3cbaeddd77e3312b2bf9098) --- .../hardware/camera2/CameraCharacteristics.java | 24 ++++++++++++++++++---- .../android/hardware/camera2/CameraDevice.java | 20 ++++++++++++------ 2 files changed, 34 insertions(+), 10 deletions(-) diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index 6ce2780c569b..9b18e9a12969 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -3142,12 +3142,26 @@ public final class CameraCharacteristics extends CameraMetadata * 
        // Returns true if the device supports the required hardware level, or better.
      * boolean isHardwareLevelSupported(CameraCharacteristics c, int requiredLevel) {
+     *     final int[] sortedHwLevels = {
+     *         CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY,
+     *         CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL,
+     *         CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED,
+     *         CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL,
+     *         CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3
+     *     };
      *     int deviceLevel = c.get(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL);
-     *     if (deviceLevel == CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY) {
-     *         return requiredLevel == deviceLevel;
+     *     if (requiredLevel == deviceLevel) {
+     *         return true;
      *     }
-     *     // deviceLevel is not LEGACY, can use numerical sort
-     *     return requiredLevel <= deviceLevel;
+     *
+     *     for (int sortedlevel : sortedHwLevels) {
+     *         if (sortedlevel == requiredLevel) {
+     *             return true;
+     *         } else if (sortedlevel == deviceLevel) {
+     *             return false;
+     *         }
+     *     }
+     *     return false; // Should never reach here
      * }
      *
        *

        At a high level, the levels are:

        @@ -3161,6 +3175,8 @@ public final class CameraCharacteristics extends CameraMetadata *
      • LEVEL_3 devices additionally support YUV reprocessing and RAW image capture, along * with additional output stream configurations.
        • + *
      • EXTERNAL devices are similar to LIMITED devices with exceptions like some sensor or + * lens information not reorted or less stable framerates.
        • *
      *

      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 diff --git a/core/java/android/hardware/camera2/CameraDevice.java b/core/java/android/hardware/camera2/CameraDevice.java index f47d4640c09c..ce88697fa8db 100644 --- a/core/java/android/hardware/camera2/CameraDevice.java +++ b/core/java/android/hardware/camera2/CameraDevice.java @@ -44,19 +44,27 @@ import java.lang.annotation.RetentionPolicy; * {@link android.Manifest.permission#CAMERA Camera} permission in its manifest * in order to access camera devices.

      * - *

      A given camera device may provide support at one of two levels: limited or - * full. If a device only supports the limited level, then Camera2 exposes a - * feature set that is roughly equivalent to the older + *

      A given camera device may provide support at one of several levels defined + * in {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}. + * If a device supports {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} level, + * the camera device is running in backward compatibility mode and has minimum camera2 API support. + * If a device supports the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} + * level, then Camera2 exposes a feature set that is roughly equivalent to the older * {@link android.hardware.Camera Camera} API, although with a cleaner and more - * efficient interface. Devices that implement the full level of support + * efficient interface. + * If a device supports the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL EXTERNAL} + * level, then the device is a removable camera that provides similar but slightly less features + * as the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} level. + * Devices that implement the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} or + * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL3} level of support * provide substantially improved capabilities over the older camera - * API. Applications that target the limited level devices will run unchanged on - * the full-level devices; if your application requires a full-level device for + * API. If your application requires a full-level device for * proper operation, declare the "android.hardware.camera.level.full" feature in your * manifest.

      * * @see CameraManager#openCamera * @see android.Manifest.permission#CAMERA + * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ public abstract class CameraDevice implements AutoCloseable { -- cgit v1.2.3-59-g8ed1b