Merge "Camera: Add visual samples for android.control.zoomRatio" into rvc-dev... (ad42ad16) · Commits · e / os / android_frameworks_base

core/java/android/hardware/camera2/CameraCharacteristics.java

+1 −1

Original line number	Original line	Diff line number	Diff line
	@@ -1214,7 +1214,7 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri
	* <p>If the camera device supports zoom-out from 1x zoom, minZoom will be less than 1.0, and		* <p>If the camera device supports zoom-out from 1x zoom, minZoom will be less than 1.0, and
	* setting {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} 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.</p>		* of view.</p>
	* <p><b>Units</b>: A pair of zoom ratio in floating points: (minZoom, maxZoom)</p>		* <p><b>Units</b>: A pair of zoom ratio in floating-points: (minZoom, maxZoom)</p>
	* <p><b>Range of valid values:</b><br></p>		* <p><b>Range of valid values:</b><br></p>
	* <p>maxZoom >= 1.0 >= minZoom</p>		* <p>maxZoom >= 1.0 >= minZoom</p>
	* <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p>		* <p><b>Optional</b> - The value for this key may be {@code null} on some devices.</p>

core/java/android/hardware/camera2/CaptureRequest.java

+60 −19

Original line number	Original line	Diff line number	Diff line
	@@ -2180,27 +2180,66 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
	* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} can still be used to specify the horizontal or vertical		* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} can still be used to specify the horizontal or vertical
	* crop to achieve aspect ratios different than the native camera sensor.</p>		* crop to achieve aspect ratios different than the native camera sensor.</p>
	* <p>By using this control, the application gains a simpler way to control zoom, which can		* <p>By using this control, the application gains a simpler way to control zoom, which can
	* be a combination of optical and digital zoom. More specifically, for a logical		* be a combination of optical and digital zoom. For example, a multi-camera system may
	* multi-camera with more than one focal length, using a floating point zoom ratio offers		* contain more than one lens with different focal lengths, and the user can use optical
	* more zoom precision when a telephoto lens is used, as well as allowing zoom ratio of		* zoom by switching between lenses. Using zoomRatio has benefits in the scenarios below:
	* less than 1.0 to zoom out to a wide field of view.</p>		* <em> Zooming in from a wide-angle lens to a telephoto lens: A floating-point ratio provides
	* <p>Note that the coordinate system of cropRegion, AE/AWB/AF regions, and faces now changes		* better precision compared to an integer value of {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}.
	* to the effective after-zoom field-of-view represented by rectangle of (0, 0,		* </em> Zooming out from a wide lens to an ultrawide lens: zoomRatio supports zoom-out whereas
	* activeArrayWidth, activeArrayHeight).</p>		* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} doesn't.</p>
	* <p>For example, if {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} is 4032*3024, and the preview stream		* <p>To illustrate, here are several scenarios of different zoom ratios, crop regions,
	* is configured to the same 4:3 aspect ratio, the application can achieve 2.0x zoom in		* and output streams, for a hypothetical camera device with an active array of size
	* one of two ways:</p>		* <code>(2000,1500)</code>.</p>
	* <ul>		* <ul>
	* <li>zoomRatio = 2.0, scaler.cropRegion = (0, 0, 4032, 3024)</li>		* <li>Camera Configuration:<ul>
	* <li>zoomRatio = 1.0 (default), scaler.cropRegion = (1008, 756, 3024, 2268)</li>		* <li>Active array size: <code>2000x1500</code> (3 MP, 4:3 aspect ratio)</li>
			* <li>Output stream #1: <code>640x480</code> (VGA, 4:3 aspect ratio)</li>
			* <li>Output stream #2: <code>1280x720</code> (720p, 16:9 aspect ratio)</li>
			* </ul>
			* </li>
			* <li>Case #1: 4:3 crop region with 2.0x zoom ratio<ul>
			* <li>Zoomed field of view: 1/4 of original field of view</li>
			* <li>Crop region: <code>Rect(0, 0, 2000, 1500) // (left, top, right, bottom)</code> (post zoom)</li>
			* </ul>
			* </li>
			* <li><img alt="4:3 aspect ratio crop diagram" src="/reference/images/camera2/metadata/android.control.zoomRatio/zoom-ratio-2-crop-43.png" /><ul>
			* <li><code>640x480</code> stream source area: <code>(0, 0, 2000, 1500)</code> (equal to crop region)</li>
			* <li><code>1280x720</code> stream source area: <code>(0, 187, 2000, 1312)</code> (letterboxed)</li>
			* </ul>
			* </li>
			* <li>Case #2: 16:9 crop region with 2.0x zoom.<ul>
			* <li>Zoomed field of view: 1/4 of original field of view</li>
			* <li>Crop region: <code>Rect(0, 187, 2000, 1312)</code></li>
			* <li><img alt="16:9 aspect ratio crop diagram" src="/reference/images/camera2/metadata/android.control.zoomRatio/zoom-ratio-2-crop-169.png" /></li>
			* <li><code>640x480</code> stream source area: <code>(250, 187, 1750, 1312)</code> (pillarboxed)</li>
			* <li><code>1280x720</code> stream source area: <code>(0, 187, 2000, 1312)</code> (equal to crop region)</li>
			* </ul>
			* </li>
			* <li>Case #3: 1:1 crop region with 0.5x zoom out to ultrawide lens.<ul>
			* <li>Zoomed field of view: 4x of original field of view (switched from wide lens to ultrawide lens)</li>
			* <li>Crop region: <code>Rect(250, 0, 1750, 1500)</code></li>
			* <li><img alt="1:1 aspect ratio crop diagram" src="/reference/images/camera2/metadata/android.control.zoomRatio/zoom-ratio-0.5-crop-11.png" /></li>
			* <li><code>640x480</code> stream source area: <code>(250, 187, 1750, 1312)</code> (letterboxed)</li>
			* <li><code>1280x720</code> stream source area: <code>(250, 328, 1750, 1172)</code> (letterboxed)</li>
			* </ul>
			* </li>
	* </ul>		* </ul>
	* <p>If the application intends to set aeRegions to be top-left quarter of the preview		* <p>As seen from the graphs above, the coordinate system of cropRegion now changes to the
	* field-of-view, the {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions} should be set to (0, 0, 2016, 1512) with		* effective after-zoom field-of-view, and is represented by the rectangle of (0, 0,
			* activeArrayWith, activeArrayHeight). The same applies to AE/AWB/AF regions, and faces.
			* This coordinate system change isn't applicable to RAW capture and its related
			* metadata such as intrinsicCalibration and lensShadingMap.</p>
			* <p>Using the same hypothetical example above, and assuming output stream #1 (640x480) is
			* the viewfinder stream, the application can achieve 2.0x zoom in one of two ways:</p>
			* <ul>
			* <li>zoomRatio = 2.0, scaler.cropRegion = (0, 0, 2000, 1500)</li>
			* <li>zoomRatio = 1.0 (default), scaler.cropRegion = (500, 375, 1500, 1125)</li>
			* </ul>
			* <p>If the application intends to set aeRegions to be top-left quarter of the viewfinder
			* field-of-view, the {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions} should be set to (0, 0, 1000, 750) with
	* zoomRatio set to 2.0. Alternatively, the application can set aeRegions to the equivalent		* zoomRatio set to 2.0. Alternatively, the application can set aeRegions to the equivalent
	* region of (1008, 756, 2016, 1512) for zoomRatio of 1.0. If the application doesn't		* region of (500, 375, 1000, 750) for zoomRatio of 1.0. If the application doesn't
	* explicitly set {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio}, its value defaults to 1.0.</p>		* explicitly set {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio}, its value defaults to 1.0.</p>
	* <p>This coordinate system change isn't applicable to RAW capture and its related metadata
	* such as intrinsicCalibration and lensShadingMap.</p>
	* <p>One limitation of controlling zoom using zoomRatio is that the {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}		* <p>One limitation of controlling zoom using zoomRatio is that the {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}
	* must only be used for letterboxing or pillarboxing of the sensor active array, and no		* must only be used for letterboxing or pillarboxing of the sensor active array, and no
	* FREEFORM cropping can be used with {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} other than 1.0.</p>		* FREEFORM cropping can be used with {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} other than 1.0.</p>
	@@ -2216,7 +2255,6 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
	* @see CameraCharacteristics#CONTROL_ZOOM_RATIO_RANGE		* @see CameraCharacteristics#CONTROL_ZOOM_RATIO_RANGE
	* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL		* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
	* @see CaptureRequest#SCALER_CROP_REGION		* @see CaptureRequest#SCALER_CROP_REGION
	* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
	*/		*/
	@PublicKey		@PublicKey
	@NonNull		@NonNull
	@@ -2574,12 +2612,15 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>>
	* frames before the lens can change to the requested focal length.		* frames before the lens can change to the requested focal length.
	* While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will		* While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
	* be set to MOVING.</p>		* be set to MOVING.</p>
	* <p>Optical zoom will not be supported on most devices.</p>		* <p>Optical zoom via this control will not be supported on most devices. Starting from API
			* level 30, the camera device may combine optical and digital zoom through the
			* {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} control.</p>
	* <p><b>Units</b>: Millimeters</p>		* <p><b>Units</b>: Millimeters</p>
	* <p><b>Range of valid values:</b><br>		* <p><b>Range of valid values:</b><br>
	* {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>		* {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>
	* <p>This key is available on all devices.</p>		* <p>This key is available on all devices.</p>
	*		*
			* @see CaptureRequest#CONTROL_ZOOM_RATIO
	* @see CaptureRequest#LENS_APERTURE		* @see CaptureRequest#LENS_APERTURE
	* @see CaptureRequest#LENS_FOCUS_DISTANCE		* @see CaptureRequest#LENS_FOCUS_DISTANCE
	* @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS		* @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS

core/java/android/hardware/camera2/CaptureResult.java

+60 −19

Original line number	Original line	Diff line number	Diff line
	@@ -2410,27 +2410,66 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
	* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} can still be used to specify the horizontal or vertical		* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} can still be used to specify the horizontal or vertical
	* crop to achieve aspect ratios different than the native camera sensor.</p>		* crop to achieve aspect ratios different than the native camera sensor.</p>
	* <p>By using this control, the application gains a simpler way to control zoom, which can		* <p>By using this control, the application gains a simpler way to control zoom, which can
	* be a combination of optical and digital zoom. More specifically, for a logical		* be a combination of optical and digital zoom. For example, a multi-camera system may
	* multi-camera with more than one focal length, using a floating point zoom ratio offers		* contain more than one lens with different focal lengths, and the user can use optical
	* more zoom precision when a telephoto lens is used, as well as allowing zoom ratio of		* zoom by switching between lenses. Using zoomRatio has benefits in the scenarios below:
	* less than 1.0 to zoom out to a wide field of view.</p>		* <em> Zooming in from a wide-angle lens to a telephoto lens: A floating-point ratio provides
	* <p>Note that the coordinate system of cropRegion, AE/AWB/AF regions, and faces now changes		* better precision compared to an integer value of {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}.
	* to the effective after-zoom field-of-view represented by rectangle of (0, 0,		* </em> Zooming out from a wide lens to an ultrawide lens: zoomRatio supports zoom-out whereas
	* activeArrayWidth, activeArrayHeight).</p>		* {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion} doesn't.</p>
	* <p>For example, if {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} is 4032*3024, and the preview stream		* <p>To illustrate, here are several scenarios of different zoom ratios, crop regions,
	* is configured to the same 4:3 aspect ratio, the application can achieve 2.0x zoom in		* and output streams, for a hypothetical camera device with an active array of size
	* one of two ways:</p>		* <code>(2000,1500)</code>.</p>
	* <ul>		* <ul>
	* <li>zoomRatio = 2.0, scaler.cropRegion = (0, 0, 4032, 3024)</li>		* <li>Camera Configuration:<ul>
	* <li>zoomRatio = 1.0 (default), scaler.cropRegion = (1008, 756, 3024, 2268)</li>		* <li>Active array size: <code>2000x1500</code> (3 MP, 4:3 aspect ratio)</li>
			* <li>Output stream #1: <code>640x480</code> (VGA, 4:3 aspect ratio)</li>
			* <li>Output stream #2: <code>1280x720</code> (720p, 16:9 aspect ratio)</li>
			* </ul>
			* </li>
			* <li>Case #1: 4:3 crop region with 2.0x zoom ratio<ul>
			* <li>Zoomed field of view: 1/4 of original field of view</li>
			* <li>Crop region: <code>Rect(0, 0, 2000, 1500) // (left, top, right, bottom)</code> (post zoom)</li>
			* </ul>
			* </li>
			* <li><img alt="4:3 aspect ratio crop diagram" src="/reference/images/camera2/metadata/android.control.zoomRatio/zoom-ratio-2-crop-43.png" /><ul>
			* <li><code>640x480</code> stream source area: <code>(0, 0, 2000, 1500)</code> (equal to crop region)</li>
			* <li><code>1280x720</code> stream source area: <code>(0, 187, 2000, 1312)</code> (letterboxed)</li>
			* </ul>
			* </li>
			* <li>Case #2: 16:9 crop region with 2.0x zoom.<ul>
			* <li>Zoomed field of view: 1/4 of original field of view</li>
			* <li>Crop region: <code>Rect(0, 187, 2000, 1312)</code></li>
			* <li><img alt="16:9 aspect ratio crop diagram" src="/reference/images/camera2/metadata/android.control.zoomRatio/zoom-ratio-2-crop-169.png" /></li>
			* <li><code>640x480</code> stream source area: <code>(250, 187, 1750, 1312)</code> (pillarboxed)</li>
			* <li><code>1280x720</code> stream source area: <code>(0, 187, 2000, 1312)</code> (equal to crop region)</li>
			* </ul>
			* </li>
			* <li>Case #3: 1:1 crop region with 0.5x zoom out to ultrawide lens.<ul>
			* <li>Zoomed field of view: 4x of original field of view (switched from wide lens to ultrawide lens)</li>
			* <li>Crop region: <code>Rect(250, 0, 1750, 1500)</code></li>
			* <li><img alt="1:1 aspect ratio crop diagram" src="/reference/images/camera2/metadata/android.control.zoomRatio/zoom-ratio-0.5-crop-11.png" /></li>
			* <li><code>640x480</code> stream source area: <code>(250, 187, 1750, 1312)</code> (letterboxed)</li>
			* <li><code>1280x720</code> stream source area: <code>(250, 328, 1750, 1172)</code> (letterboxed)</li>
			* </ul>
			* </li>
	* </ul>		* </ul>
	* <p>If the application intends to set aeRegions to be top-left quarter of the preview		* <p>As seen from the graphs above, the coordinate system of cropRegion now changes to the
	* field-of-view, the {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions} should be set to (0, 0, 2016, 1512) with		* effective after-zoom field-of-view, and is represented by the rectangle of (0, 0,
			* activeArrayWith, activeArrayHeight). The same applies to AE/AWB/AF regions, and faces.
			* This coordinate system change isn't applicable to RAW capture and its related
			* metadata such as intrinsicCalibration and lensShadingMap.</p>
			* <p>Using the same hypothetical example above, and assuming output stream #1 (640x480) is
			* the viewfinder stream, the application can achieve 2.0x zoom in one of two ways:</p>
			* <ul>
			* <li>zoomRatio = 2.0, scaler.cropRegion = (0, 0, 2000, 1500)</li>
			* <li>zoomRatio = 1.0 (default), scaler.cropRegion = (500, 375, 1500, 1125)</li>
			* </ul>
			* <p>If the application intends to set aeRegions to be top-left quarter of the viewfinder
			* field-of-view, the {@link CaptureRequest#CONTROL_AE_REGIONS android.control.aeRegions} should be set to (0, 0, 1000, 750) with
	* zoomRatio set to 2.0. Alternatively, the application can set aeRegions to the equivalent		* zoomRatio set to 2.0. Alternatively, the application can set aeRegions to the equivalent
	* region of (1008, 756, 2016, 1512) for zoomRatio of 1.0. If the application doesn't		* region of (500, 375, 1000, 750) for zoomRatio of 1.0. If the application doesn't
	* explicitly set {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio}, its value defaults to 1.0.</p>		* explicitly set {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio}, its value defaults to 1.0.</p>
	* <p>This coordinate system change isn't applicable to RAW capture and its related metadata
	* such as intrinsicCalibration and lensShadingMap.</p>
	* <p>One limitation of controlling zoom using zoomRatio is that the {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}		* <p>One limitation of controlling zoom using zoomRatio is that the {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}
	* must only be used for letterboxing or pillarboxing of the sensor active array, and no		* must only be used for letterboxing or pillarboxing of the sensor active array, and no
	* FREEFORM cropping can be used with {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} other than 1.0.</p>		* FREEFORM cropping can be used with {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} other than 1.0.</p>
	@@ -2446,7 +2485,6 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
	* @see CameraCharacteristics#CONTROL_ZOOM_RATIO_RANGE		* @see CameraCharacteristics#CONTROL_ZOOM_RATIO_RANGE
	* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL		* @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL
	* @see CaptureRequest#SCALER_CROP_REGION		* @see CaptureRequest#SCALER_CROP_REGION
	* @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE
	*/		*/
	@PublicKey		@PublicKey
	@NonNull		@NonNull
	@@ -2848,12 +2886,15 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> {
	* frames before the lens can change to the requested focal length.		* frames before the lens can change to the requested focal length.
	* While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will		* While the focal length is still changing, {@link CaptureResult#LENS_STATE android.lens.state} will
	* be set to MOVING.</p>		* be set to MOVING.</p>
	* <p>Optical zoom will not be supported on most devices.</p>		* <p>Optical zoom via this control will not be supported on most devices. Starting from API
			* level 30, the camera device may combine optical and digital zoom through the
			* {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} control.</p>
	* <p><b>Units</b>: Millimeters</p>		* <p><b>Units</b>: Millimeters</p>
	* <p><b>Range of valid values:</b><br>		* <p><b>Range of valid values:</b><br>
	* {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>		* {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>
	* <p>This key is available on all devices.</p>		* <p>This key is available on all devices.</p>
	*		*
			* @see CaptureRequest#CONTROL_ZOOM_RATIO
	* @see CaptureRequest#LENS_APERTURE		* @see CaptureRequest#LENS_APERTURE
	* @see CaptureRequest#LENS_FOCUS_DISTANCE		* @see CaptureRequest#LENS_FOCUS_DISTANCE
	* @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS		* @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS

docs/html/reference/images/camera2/metadata/android.control.zoomRatio/zoom-ratio-0.5-crop-11.png

0 → 100644

+27.8 KiB

Loading image diff...

docs/html/reference/images/camera2/metadata/android.control.zoomRatio/zoom-ratio-2-crop-169.png

0 → 100644

+24.9 KiB

Loading image diff...