@ -1895,27 +1895,66 @@ typedef enum acamera_metadata_tag {
* ACAMERA_SCALER_CROP_REGION can still be used to specify the horizontal or vertical
* ACAMERA_SCALER_CROP_REGION 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 ACAMERA_SCALER_CROP_REGION .
* 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 >
* ACAMERA_SCALER_CROP_REGION doesn ' t . < / p >
* < p > For example , if ACAMERA_SENSOR_INFO_ACTIVE_ARRAY_SIZE 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.0 x 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 > 2000 x1500 < / code > ( 3 MP , 4 : 3 aspect ratio ) < / li >
* < li > Output stream # 1 : < code > 640 x480 < / code > ( VGA , 4 : 3 aspect ratio ) < / li >
* < li > Output stream # 2 : < code > 1280 x720 < / code > ( 720 p , 16 : 9 aspect ratio ) < / li >
* < / ul >
* < / li >
* < li > Case # 1 : 4 : 3 crop region with 2.0 x 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 = " ../images/camera2/metadata/android.control.zoomRatio/zoom-ratio-2-crop-43.png " / > < ul >
* < li > < code > 640 x480 < / code > stream source area : < code > ( 0 , 0 , 2000 , 1500 ) < / code > ( equal to crop region ) < / li >
* < li > < code > 1280 x720 < / code > stream source area : < code > ( 0 , 187 , 2000 , 1312 ) < / code > ( letterboxed ) < / li >
* < / ul >
* < / ul >
* < p > If the application intends to set aeRegions to be top - left quarter of the preview
* < / li >
* field - of - view , the ACAMERA_CONTROL_AE_REGIONS should be set to ( 0 , 0 , 2016 , 1512 ) with
* < li > Case # 2 : 16 : 9 crop region with 2.0 x 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 = " ../images/camera2/metadata/android.control.zoomRatio/zoom-ratio-2-crop-169.png " / > < / li >
* < li > < code > 640 x480 < / code > stream source area : < code > ( 250 , 187 , 1750 , 1312 ) < / code > ( pillarboxed ) < / li >
* < li > < code > 1280 x720 < / 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.5 x zoom out to ultrawide lens . < ul >
* < li > Zoomed field of view : 4 x 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 = " ../images/camera2/metadata/android.control.zoomRatio/zoom-ratio-0.5-crop-11.png " / > < / li >
* < li > < code > 640 x480 < / code > stream source area : < code > ( 250 , 187 , 1750 , 1312 ) < / code > ( letterboxed ) < / li >
* < li > < code > 1280 x720 < / code > stream source area : < code > ( 250 , 328 , 1750 , 1172 ) < / code > ( letterboxed ) < / li >
* < / ul >
* < / li >
* < / ul >
* < p > As seen from the graphs above , the coordinate system of cropRegion now changes to the
* 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 ( 640 x480 ) is
* the viewfinder stream , the application can achieve 2.0 x 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 ACAMERA_CONTROL_AE_REGIONS 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 ACAMERA_CONTROL_ZOOM_RATIO , its value defaults to 1.0 . < / p >
* explicitly set ACAMERA_CONTROL_ZOOM_RATIO , 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 ACAMERA_SCALER_CROP_REGION
* < p > One limitation of controlling zoom using zoomRatio is that the ACAMERA_SCALER_CROP_REGION
* 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 ACAMERA_CONTROL_ZOOM_RATIO other than 1.0 . < / p >
* FREEFORM cropping can be used with ACAMERA_CONTROL_ZOOM_RATIO other than 1.0 . < / p >
@ -1923,7 +1962,6 @@ typedef enum acamera_metadata_tag {
* @ see ACAMERA_CONTROL_AE_REGIONS
* @ see ACAMERA_CONTROL_AE_REGIONS
* @ see ACAMERA_CONTROL_ZOOM_RATIO
* @ see ACAMERA_CONTROL_ZOOM_RATIO
* @ see ACAMERA_SCALER_CROP_REGION
* @ see ACAMERA_SCALER_CROP_REGION
* @ see ACAMERA_SENSOR_INFO_ACTIVE_ARRAY_SIZE
*/
*/
ACAMERA_CONTROL_ZOOM_RATIO = // float
ACAMERA_CONTROL_ZOOM_RATIO = // float
ACAMERA_CONTROL_START + 47 ,
ACAMERA_CONTROL_START + 47 ,
@ -2395,8 +2433,11 @@ typedef enum acamera_metadata_tag {
* 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 , ACAMERA_LENS_STATE will
* While the focal length is still changing , ACAMERA_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
* ACAMERA_CONTROL_ZOOM_RATIO control . < / p >
*
*
* @ see ACAMERA_CONTROL_ZOOM_RATIO
* @ see ACAMERA_LENS_APERTURE
* @ see ACAMERA_LENS_APERTURE
* @ see ACAMERA_LENS_FOCUS_DISTANCE
* @ see ACAMERA_LENS_FOCUS_DISTANCE
* @ see ACAMERA_LENS_STATE
* @ see ACAMERA_LENS_STATE