summaryrefslogtreecommitdiffstats
path: root/camera
diff options
context:
space:
mode:
Diffstat (limited to 'camera')
-rw-r--r--camera/docs/docs.html55
-rw-r--r--camera/docs/metadata_definitions.xml36
2 files changed, 59 insertions, 32 deletions
diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index bda9616..a454738 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -4850,10 +4850,8 @@ view may be smaller than when bokeh mode is off.<wbr/></p>
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="6">
- <p>Instead of using <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> with dual purposes of crop and zoom,<wbr/> the
-application can now choose to use this tag to specify the desired zoom level.<wbr/> The
-<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> can still be used to specify the horizontal or vertical
-crop to achieve aspect ratios different than the native camera sensor.<wbr/></p>
+ <p>Instead of using <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> for zoom,<wbr/> the application can now choose to
+use this tag to specify the desired zoom level.<wbr/></p>
<p>By using this control,<wbr/> the application gains a simpler way to control zoom,<wbr/> which can
be a combination of optical and digital zoom.<wbr/> For example,<wbr/> a multi-camera system may
contain more than one lens with different focal lengths,<wbr/> and the user can use optical
@@ -4919,7 +4917,10 @@ region of (500,<wbr/> 375,<wbr/> 1000,<wbr/> 750) for zoomRatio of 1.<wbr/>0.<wb
explicitly set <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a>,<wbr/> its value defaults to 1.<wbr/>0.<wbr/></p>
<p>One limitation of controlling zoom using zoomRatio is that the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>
must only be used for letterboxing or pillarboxing of the sensor active array,<wbr/> and no
-FREEFORM cropping can be used with <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> other than 1.<wbr/>0.<wbr/></p>
+FREEFORM cropping can be used with <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> other than 1.<wbr/>0.<wbr/> If
+<a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> is not 1.<wbr/>0,<wbr/> and <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> is set to be
+windowboxing,<wbr/> the camera framework will override the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to be
+the active array.<wbr/></p>
</td>
</tr>
@@ -6636,12 +6637,11 @@ of view.<wbr/></p>
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="6">
- <p>When the key is reported,<wbr/> the camera device must be setting
-<a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a> to be the same as maxZoom.<wbr/> The camera framework
-makes sure to always controls zoom via <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a>.<wbr/> The
-<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> 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.<wbr/></p>
+ <p>When the key is reported,<wbr/> the camera device's <a href="#static_android.scaler.availableMaxDigitalZoom">android.<wbr/>scaler.<wbr/>available<wbr/>Max<wbr/>Digital<wbr/>Zoom</a>
+must be less than or equal to maxZoom.<wbr/> The camera framework makes sure to always
+control zoom via <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a>.<wbr/> The <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> 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.<wbr/></p>
<p>For a logical multi-camera device,<wbr/> this key must either be reported for both the logical
camera device and all its physical sub-cameras,<wbr/> or none of them.<wbr/></p>
<p>When the key is not reported,<wbr/> camera framework derives the application-facing
@@ -10487,10 +10487,8 @@ view may be smaller than when bokeh mode is off.<wbr/></p>
</tr>
<tr class="entry_cont">
<td class="entry_details" colspan="6">
- <p>Instead of using <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> with dual purposes of crop and zoom,<wbr/> the
-application can now choose to use this tag to specify the desired zoom level.<wbr/> The
-<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> can still be used to specify the horizontal or vertical
-crop to achieve aspect ratios different than the native camera sensor.<wbr/></p>
+ <p>Instead of using <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> for zoom,<wbr/> the application can now choose to
+use this tag to specify the desired zoom level.<wbr/></p>
<p>By using this control,<wbr/> the application gains a simpler way to control zoom,<wbr/> which can
be a combination of optical and digital zoom.<wbr/> For example,<wbr/> a multi-camera system may
contain more than one lens with different focal lengths,<wbr/> and the user can use optical
@@ -10556,7 +10554,10 @@ region of (500,<wbr/> 375,<wbr/> 1000,<wbr/> 750) for zoomRatio of 1.<wbr/>0.<wb
explicitly set <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a>,<wbr/> its value defaults to 1.<wbr/>0.<wbr/></p>
<p>One limitation of controlling zoom using zoomRatio is that the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a>
must only be used for letterboxing or pillarboxing of the sensor active array,<wbr/> and no
-FREEFORM cropping can be used with <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> other than 1.<wbr/>0.<wbr/></p>
+FREEFORM cropping can be used with <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> other than 1.<wbr/>0.<wbr/> If
+<a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> is not 1.<wbr/>0,<wbr/> and <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> is set to be
+windowboxing,<wbr/> the camera framework will override the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to be
+the active array.<wbr/></p>
</td>
</tr>
@@ -19652,11 +19653,18 @@ and
respectively.<wbr/></p>
<p>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.<wbr/></p>
+<p>The camera sensor output aspect ratio depends on factors such as output stream
+combination and <a href="#controls_android.control.aeTargetFpsRange">android.<wbr/>control.<wbr/>ae<wbr/>Target<wbr/>Fps<wbr/>Range</a>,<wbr/> and shouldn't be adjusted by using
+this control.<wbr/> And the camera device will treat different camera sensor output sizes
+(potentially with in-sensor crop) as the same crop of
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/> As a result,<wbr/> the application shouldn't assume the
+maximum crop region always maps to the same aspect ratio or field of view for the
+sensor output.<wbr/></p>
<p>Starting from API level 30,<wbr/> it's strongly recommended to use <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a>
to take advantage of better support for zoom with logical multi-camera.<wbr/> The benefits
include better precision with optical-digital zoom combination,<wbr/> and ability to do
zoom-out from 1.<wbr/>0x.<wbr/> When using <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> for zoom,<wbr/> the crop region in
-the capture request must be either letterboxing or pillarboxing (but not both).<wbr/> The
+the capture request should be left as the default activeArray size.<wbr/> The
coordinate system is post-zoom,<wbr/> meaning that the activeArraySize or
preCorrectionActiveArraySize covers the camera device's field of view "after" zoom.<wbr/> See
<a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> for details.<wbr/></p>
@@ -21403,7 +21411,9 @@ windowboxing.<wbr/></li>
</ol>
</li>
<li>Setting <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> to values different than 1.<wbr/>0 and
-<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to be windowboxing at the same time is undefined behavior.<wbr/></li>
+<a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to be windowboxing at the same time are not supported.<wbr/> In this
+case,<wbr/> the camera framework will override the <a href="#controls_android.scaler.cropRegion">android.<wbr/>scaler.<wbr/>crop<wbr/>Region</a> to be the active
+array.<wbr/></li>
</ul>
<p>LEGACY capability devices will only support CENTER_<wbr/>ONLY cropping.<wbr/></p>
</td>
@@ -22024,11 +22034,18 @@ and
respectively.<wbr/></p>
<p>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.<wbr/></p>
+<p>The camera sensor output aspect ratio depends on factors such as output stream
+combination and <a href="#controls_android.control.aeTargetFpsRange">android.<wbr/>control.<wbr/>ae<wbr/>Target<wbr/>Fps<wbr/>Range</a>,<wbr/> and shouldn't be adjusted by using
+this control.<wbr/> And the camera device will treat different camera sensor output sizes
+(potentially with in-sensor crop) as the same crop of
+<a href="#static_android.sensor.info.activeArraySize">android.<wbr/>sensor.<wbr/>info.<wbr/>active<wbr/>Array<wbr/>Size</a>.<wbr/> As a result,<wbr/> the application shouldn't assume the
+maximum crop region always maps to the same aspect ratio or field of view for the
+sensor output.<wbr/></p>
<p>Starting from API level 30,<wbr/> it's strongly recommended to use <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a>
to take advantage of better support for zoom with logical multi-camera.<wbr/> The benefits
include better precision with optical-digital zoom combination,<wbr/> and ability to do
zoom-out from 1.<wbr/>0x.<wbr/> When using <a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> for zoom,<wbr/> the crop region in
-the capture request must be either letterboxing or pillarboxing (but not both).<wbr/> The
+the capture request should be left as the default activeArray size.<wbr/> The
coordinate system is post-zoom,<wbr/> meaning that the activeArraySize or
preCorrectionActiveArraySize covers the camera device's field of view "after" zoom.<wbr/> See
<a href="#controls_android.control.zoomRatio">android.<wbr/>control.<wbr/>zoom<wbr/>Ratio</a> for details.<wbr/></p>
diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index ca35e8d..e226193 100644
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -3239,12 +3239,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
of view.
</details>
<hal_details>
- 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
- ratio.
+ 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
</description>
<range>android.control.zoomRatioRange</range>
<details>
- 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.
</details>
<hal_details>
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
windowboxing.
* 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
+ array.
LEGACY capability devices will only support CENTER_ONLY cropping.
</details>