diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index b60586655dc8b..aa2097e872b23 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -1212,7 +1212,7 @@ public final class CameraCharacteristics extends CameraMetadataMinimum and maximum zoom ratios supported by this camera device.

*

If the camera device supports zoom-out from 1x zoom, minZoom will be less than 1.0, and - * setting android.control.zoomRation to values less than 1.0 increases the camera's field + * setting {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} to values less than 1.0 increases the camera's field * of view.

*

Units: A pair of zoom ratio in floating points: (minZoom, maxZoom)

*

Range of valid values:

@@ -1222,6 +1222,7 @@ public final class CameraCharacteristics extends CameraMetadata * + * @see CaptureRequest#CONTROL_ZOOM_RATIO * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL */ @PublicKey diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index 6bf57834ae6c6..daca61fae7b66 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -2154,7 +2154,7 @@ public final class CaptureRequest extends CameraMetadata> * stream combinations of LIMITED hardware level are guaranteed.

*

For a logical multi-camera, bokeh may be implemented by stereo vision from sub-cameras * with different field of view. As a result, when bokeh mode is enabled, the camera device - * may override android.scaler.CropRegion, and the field of view will be smaller than when + * may override {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}, and the field of view will be smaller than when * bokeh mode is off.

*

Possible values: *

    @@ -2163,6 +2163,8 @@ public final class CaptureRequest extends CameraMetadata> *
  • {@link #CONTROL_BOKEH_MODE_CONTINUOUS CONTINUOUS}
    • *

*

Optional - The value for this key may be {@code null} on some devices.

+ * + * @see CaptureRequest#SCALER_CROP_REGION * @see #CONTROL_BOKEH_MODE_OFF * @see #CONTROL_BOKEH_MODE_STILL_CAPTURE * @see #CONTROL_BOKEH_MODE_CONTINUOUS @@ -2740,32 +2742,70 @@ public final class CaptureRequest extends CameraMetadata> *

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 + *

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 * match the output's configured resolution.

- *

The crop region is applied after the RAW to other color - * space (e.g. YUV) conversion. Since raw streams - * (e.g. RAW16) don't have the conversion stage, they are not + *

The crop region is applied after the RAW to other color space (e.g. YUV) + * conversion. Since raw streams (e.g. RAW16) don't have the conversion stage, they are not * croppable. The crop region will be ignored by raw streams.

- *

For non-raw streams, any additional per-stream cropping will - * be done to maximize the final pixel area of the stream.

- *

For example, if the crop region is set to a 4:3 aspect - * ratio, then 4:3 streams will use the exact crop - * region. 16:9 streams will further crop vertically - * (letterbox).

- *

Conversely, if the crop region is set to a 16:9, then 4:3 - * outputs will crop horizontally (pillarbox), and 16:9 - * streams will match exactly. These additional crops will - * be centered within the crop region.

+ *

For non-raw streams, any additional per-stream cropping will be done to maximize the + * final pixel area of the stream.

+ *

For example, if the crop region is set to a 4:3 aspect ratio, then 4:3 streams will use + * the exact crop region. 16:9 streams will further crop vertically (letterbox).

+ *

Conversely, if the crop region is set to a 16:9, then 4:3 outputs will crop horizontally + * (pillarbox), and 16:9 streams will match exactly. These additional crops will be + * centered within the crop region.

+ *

To illustrate, here are several scenarios of different crop regions and output streams, + * for a hypothetical camera device with an active array of size (2000,1500). Note that + * several of these examples use non-centered crop regions for ease of illustration; such + * regions are only supported on devices with FREEFORM capability + * ({@link CameraCharacteristics#SCALER_CROPPING_TYPE android.scaler.croppingType} == FREEFORM), but this does not affect the way the crop + * rules work otherwise.

+ *
    + *
  • Camera Configuration:
      + *
    • Active array size: 2000x1500 (3 MP, 4:3 aspect ratio)
      • + *
    • Output stream #1: 640x480 (VGA, 4:3 aspect ratio)
      • + *
    • Output stream #2: 1280x720 (720p, 16:9 aspect ratio)
      • + *
    + *
    • + *
  • Case #1: 4:3 crop region with 2x digital zoom
      + *
    • Crop region: Rect(500, 375, 1500, 1125) // (left, top, right, bottom)
      • + *
    • 4:3 aspect ratio crop diagram
      • + *
    • 640x480 stream source area: (500, 375, 1500, 1125) (equal to crop region)
      • + *
    • 1280x720 stream source area: (500, 469, 1500, 1031) (letterboxed)
      • + *
    + *
    • + *
  • Case #2: 16:9 crop region with ~1.5x digital zoom.
      + *
    • Crop region: Rect(500, 375, 1833, 1125)
      • + *
    • 16:9 aspect ratio crop diagram
      • + *
    • 640x480 stream source area: (666, 375, 1666, 1125) (pillarboxed)
      • + *
    • 1280x720 stream source area: (500, 375, 1833, 1125) (equal to crop region)
      • + *
    + *
    • + *
  • Case #3: 1:1 crop region with ~2.6x digital zoom.
      + *
    • Crop region: Rect(500, 375, 1250, 1125)
      • + *
    • 1:1 aspect ratio crop diagram
      • + *
    • 640x480 stream source area: (500, 469, 1250, 1031) (letterboxed)
      • + *
    • 1280x720 stream source area: (500, 543, 1250, 957) (letterboxed)
      • + *
    + *
    • + *
  • Case #4: Replace 640x480 stream with 1024x1024 stream, with 4:3 crop region:
      + *
    • Crop region: Rect(500, 375, 1500, 1125)
      • + *
    • Square output, 4:3 aspect ratio crop diagram
      • + *
    • 1024x1024 stream source area: (625, 375, 1375, 1125) (pillarboxed)
      • + *
    • 1280x720 stream source area: (500, 469, 1500, 1031) (letterboxed)
      • + *
    • Note that in this case, neither of the two outputs is a subset of the other, with + * each containing image data the other doesn't have.
      • + *
    + *
    • + *
*

If the coordinate system is {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, 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 @@ -2776,18 +2816,16 @@ public final class CaptureRequest extends CameraMetadata> * 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.

+ *

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.

*

Starting from API level 30, it's strongly recommended to use {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} * to take advantage of better support for zoom with logical multi-camera. The benefits * include better precision with optical-digital zoom combination, and ability to do * zoom-out from 1.0x. When using {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} for zoom, the crop region in * the capture request must be either letterboxing or pillarboxing (but not both). The * coordinate system is post-zoom, meaning that the activeArraySize or - * preCorrectionActiveArraySize covers the camera device's field of view "after" zoom. - * See {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} for details.

+ * preCorrectionActiveArraySize covers the camera device's field of view "after" zoom. See + * {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} for details.

*

Units: Pixel coordinates relative to * {@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 @@ -2797,6 +2835,7 @@ public final class CaptureRequest extends CameraMetadata> * @see CaptureRequest#CONTROL_ZOOM_RATIO * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM + * @see CameraCharacteristics#SCALER_CROPPING_TYPE * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index c9956231f34cf..96147e45f27a7 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -2384,7 +2384,7 @@ public class CaptureResult extends CameraMetadata> { * stream combinations of LIMITED hardware level are guaranteed.

*

For a logical multi-camera, bokeh may be implemented by stereo vision from sub-cameras * with different field of view. As a result, when bokeh mode is enabled, the camera device - * may override android.scaler.CropRegion, and the field of view will be smaller than when + * may override {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}, and the field of view will be smaller than when * bokeh mode is off.

*

Possible values: *

    @@ -2393,6 +2393,8 @@ public class CaptureResult extends CameraMetadata> { *
  • {@link #CONTROL_BOKEH_MODE_CONTINUOUS CONTINUOUS}
    • *

*

Optional - The value for this key may be {@code null} on some devices.

+ * + * @see CaptureRequest#SCALER_CROP_REGION * @see #CONTROL_BOKEH_MODE_OFF * @see #CONTROL_BOKEH_MODE_STILL_CAPTURE * @see #CONTROL_BOKEH_MODE_CONTINUOUS @@ -3379,32 +3381,70 @@ public class CaptureResult extends CameraMetadata> { *

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 + *

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 * match the output's configured resolution.

- *

The crop region is applied after the RAW to other color - * space (e.g. YUV) conversion. Since raw streams - * (e.g. RAW16) don't have the conversion stage, they are not + *

The crop region is applied after the RAW to other color space (e.g. YUV) + * conversion. Since raw streams (e.g. RAW16) don't have the conversion stage, they are not * croppable. The crop region will be ignored by raw streams.

- *

For non-raw streams, any additional per-stream cropping will - * be done to maximize the final pixel area of the stream.

- *

For example, if the crop region is set to a 4:3 aspect - * ratio, then 4:3 streams will use the exact crop - * region. 16:9 streams will further crop vertically - * (letterbox).

- *

Conversely, if the crop region is set to a 16:9, then 4:3 - * outputs will crop horizontally (pillarbox), and 16:9 - * streams will match exactly. These additional crops will - * be centered within the crop region.

+ *

For non-raw streams, any additional per-stream cropping will be done to maximize the + * final pixel area of the stream.

+ *

For example, if the crop region is set to a 4:3 aspect ratio, then 4:3 streams will use + * the exact crop region. 16:9 streams will further crop vertically (letterbox).

+ *

Conversely, if the crop region is set to a 16:9, then 4:3 outputs will crop horizontally + * (pillarbox), and 16:9 streams will match exactly. These additional crops will be + * centered within the crop region.

+ *

To illustrate, here are several scenarios of different crop regions and output streams, + * for a hypothetical camera device with an active array of size (2000,1500). Note that + * several of these examples use non-centered crop regions for ease of illustration; such + * regions are only supported on devices with FREEFORM capability + * ({@link CameraCharacteristics#SCALER_CROPPING_TYPE android.scaler.croppingType} == FREEFORM), but this does not affect the way the crop + * rules work otherwise.

+ *
    + *
  • Camera Configuration:
      + *
    • Active array size: 2000x1500 (3 MP, 4:3 aspect ratio)
      • + *
    • Output stream #1: 640x480 (VGA, 4:3 aspect ratio)
      • + *
    • Output stream #2: 1280x720 (720p, 16:9 aspect ratio)
      • + *
    + *
    • + *
  • Case #1: 4:3 crop region with 2x digital zoom
      + *
    • Crop region: Rect(500, 375, 1500, 1125) // (left, top, right, bottom)
      • + *
    • 4:3 aspect ratio crop diagram
      • + *
    • 640x480 stream source area: (500, 375, 1500, 1125) (equal to crop region)
      • + *
    • 1280x720 stream source area: (500, 469, 1500, 1031) (letterboxed)
      • + *
    + *
    • + *
  • Case #2: 16:9 crop region with ~1.5x digital zoom.
      + *
    • Crop region: Rect(500, 375, 1833, 1125)
      • + *
    • 16:9 aspect ratio crop diagram
      • + *
    • 640x480 stream source area: (666, 375, 1666, 1125) (pillarboxed)
      • + *
    • 1280x720 stream source area: (500, 375, 1833, 1125) (equal to crop region)
      • + *
    + *
    • + *
  • Case #3: 1:1 crop region with ~2.6x digital zoom.
      + *
    • Crop region: Rect(500, 375, 1250, 1125)
      • + *
    • 1:1 aspect ratio crop diagram
      • + *
    • 640x480 stream source area: (500, 469, 1250, 1031) (letterboxed)
      • + *
    • 1280x720 stream source area: (500, 543, 1250, 957) (letterboxed)
      • + *
    + *
    • + *
  • Case #4: Replace 640x480 stream with 1024x1024 stream, with 4:3 crop region:
      + *
    • Crop region: Rect(500, 375, 1500, 1125)
      • + *
    • Square output, 4:3 aspect ratio crop diagram
      • + *
    • 1024x1024 stream source area: (625, 375, 1375, 1125) (pillarboxed)
      • + *
    • 1280x720 stream source area: (500, 469, 1500, 1031) (letterboxed)
      • + *
    • Note that in this case, neither of the two outputs is a subset of the other, with + * each containing image data the other doesn't have.
      • + *
    + *
    • + *
*

If the coordinate system is {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, 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 @@ -3415,18 +3455,16 @@ public class CaptureResult extends CameraMetadata> { * 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.

+ *

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.

*

Starting from API level 30, it's strongly recommended to use {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} * to take advantage of better support for zoom with logical multi-camera. The benefits * include better precision with optical-digital zoom combination, and ability to do * zoom-out from 1.0x. When using {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} for zoom, the crop region in * the capture request must be either letterboxing or pillarboxing (but not both). The * coordinate system is post-zoom, meaning that the activeArraySize or - * preCorrectionActiveArraySize covers the camera device's field of view "after" zoom. - * See {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} for details.

+ * preCorrectionActiveArraySize covers the camera device's field of view "after" zoom. See + * {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} for details.

*

Units: Pixel coordinates relative to * {@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 @@ -3436,6 +3474,7 @@ public class CaptureResult extends CameraMetadata> { * @see CaptureRequest#CONTROL_ZOOM_RATIO * @see CaptureRequest#DISTORTION_CORRECTION_MODE * @see CameraCharacteristics#SCALER_AVAILABLE_MAX_DIGITAL_ZOOM + * @see CameraCharacteristics#SCALER_CROPPING_TYPE * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ diff --git a/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-11-ratio.png b/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-11-ratio.png new file mode 100644 index 0000000000000..b6c07656e3254 Binary files /dev/null and b/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-11-ratio.png differ diff --git a/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-169-ratio.png b/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-169-ratio.png new file mode 100644 index 0000000000000..4e975e55514c5 Binary files /dev/null and b/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-169-ratio.png differ diff --git a/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-43-ratio.png b/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-43-ratio.png new file mode 100644 index 0000000000000..a331095df2dd4 Binary files /dev/null and b/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-43-ratio.png differ diff --git a/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-43-square-ratio.png b/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-43-square-ratio.png new file mode 100644 index 0000000000000..41e666854d21c Binary files /dev/null and b/docs/html/reference/images/camera2/metadata/android.scaler.cropRegion/crop-region-43-square-ratio.png differ