diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index ca35e8d..e226193 100644
@@ -3239,12 +3239,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
- When the key is reported, the camera device must be setting
- android.scaler.availableMaxDigitalZoom to be the same as maxZoom. The camera framework
- makes sure to always controls zoom via android.control.zoomRatio. The
- android.scaler.cropRegion tag is only used to do horizontal or vertical cropping (but
- not both) to achieve aspect ratio different than the camera sensor's native aspect
+ When the key is reported, the camera device's android.scaler.availableMaxDigitalZoom
+ must be less than or equal to maxZoom. The camera framework makes sure to always
+ control zoom via android.control.zoomRatio. The android.scaler.cropRegion tag is only
+ used to do horizontal or vertical cropping (but not both) to achieve aspect ratio
+ different than the camera sensor's native aspect ratio.
For a logical multi-camera device, this key must either be reported for both the logical
camera device and all its physical sub-cameras, or none of them.
@@ -3262,10 +3261,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
- Instead of using android.scaler.cropRegion with dual purposes of crop and zoom, the
- application can now choose to use this tag to specify the desired zoom level. The
- android.scaler.cropRegion can still be used to specify the horizontal or vertical
- crop to achieve aspect ratios different than the native camera sensor.
+ Instead of using android.scaler.cropRegion for zoom, the application can now choose to
+ use this tag to specify the desired zoom level.
By using this control, the application gains a simpler way to control zoom, which can
be a combination of optical and digital zoom. For example, a multi-camera system may
@@ -3324,7 +3321,10 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
One limitation of controlling zoom using zoomRatio is that the android.scaler.cropRegion
must only be used for letterboxing or pillarboxing of the sensor active array, and no
- FREEFORM cropping can be used with android.control.zoomRatio other than 1.0.
+ FREEFORM cropping can be used with android.control.zoomRatio other than 1.0. If
+ android.control.zoomRatio is not 1.0, and android.scaler.cropRegion is set to be
+ windowboxing, the camera framework will override the android.scaler.cropRegion to be
+ the active array.
For all capture request templates, this field must be set to 1.0 in order to have
@@ -6374,11 +6374,19 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
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 sensor output aspect ratio depends on factors such as output stream
+ combination and android.control.aeTargetFpsRange, and shouldn't be adjusted by using
+ this control. And the camera device will treat different camera sensor output sizes
+ (potentially with in-sensor crop) as the same crop of
+ android.sensor.info.activeArraySize. As a result, the application shouldn't assume the
+ maximum crop region always maps to the same aspect ratio or field of view for the
+ sensor output.
Starting from API level 30, it's strongly recommended to use 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 android.control.zoomRatio for zoom, the crop region in
- the capture request must be either letterboxing or pillarboxing (but not both). The
+ the capture request should be left as the default activeArray size. The
coordinate system is post-zoom, meaning that the activeArraySize or
preCorrectionActiveArraySize covers the camera device's field of view "after" zoom. See
android.control.zoomRatio for details.
@@ -7196,7 +7204,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
the field of view vertically (letterboxing) or horizontally (pillarboxing), but not
* Setting android.control.zoomRatio to values different than 1.0 and
- android.scaler.cropRegion to be windowboxing at the same time is undefined behavior.
+ android.scaler.cropRegion to be windowboxing at the same time are not supported. In this
+ case, the camera framework will override the android.scaler.cropRegion to be the active
LEGACY capability devices will only support CENTER_ONLY cropping.