Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 8f463c2f authored by Shuzhen Wang's avatar Shuzhen Wang Committed by Android (Google) Code Review
Browse files

Merge "Camera: Update docs for focalLength" into main

parents cc35bfa8 4baed8fc

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

+3 −4
Original line number Diff line number Diff line
@@ -1823,10 +1823,9 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 
    /**

     * <p>List of focal lengths for {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength} that are supported by this camera

     * device.</p>

     * <p>If optical zoom is not supported, this list will only contain

     * a single value corresponding to the fixed focal length of the

     * device. Otherwise, this list will include every focal length supported

     * by the camera device, in ascending order.</p>

     * <p>In most cases this list will only contain a single value corresponding

     * to the fixed focal length of the device. Otherwise, this list will include

     * every focal length supported by the camera device, in ascending order.</p>

     * <p><b>Units</b>: Millimeters</p>

     * <p><b>Range of valid values:</b><br></p>

     * <p>Values are &gt; 0</p>

core/java/android/hardware/camera2/CameraMetadata.java

+5 −9
Original line number Diff line number Diff line
@@ -982,15 +982,10 @@ public abstract class CameraMetadata<TKey> { 
     * <p>The field of view of non-RAW physical streams must not be smaller than that of the

     * non-RAW logical streams, or the maximum field-of-view of the physical camera,

     * whichever is smaller. The application should check the physical capture result

     * metadata for how the physical streams are cropped or zoomed. More specifically, given

     * the physical camera result metadata, the effective horizontal field-of-view of the

     * physical camera is:</p>

     * <pre><code>fov = 2 * atan2(cropW * sensorW / (2 * zoomRatio * activeArrayW), focalLength)

     * </code></pre>

     * <p>where the equation parameters are the physical camera's crop region width, physical

     * sensor width, zoom ratio, active array width, and focal length respectively. Typically

     * the physical stream of active physical camera has the same field-of-view as the

     * logical streams. However, the same may not be true for physical streams from

     * metadata and physical camera characteristics for how the physical streams are cropped

     * or zoomed. See {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength} on how field-of-view is calculated.</p>

     * <p>Typically the physical stream of active physical camera has the same field-of-view as

     * the logical streams. However, the same may not be true for physical streams from

     * non-active physical cameras. For example, if the logical camera has a wide-ultrawide

     * configuration where the wide lens is the default, when the crop region is set to the

     * logical camera's active array size, (and the zoom ratio set to 1.0 starting from
@@ -1038,6 +1033,7 @@ public abstract class CameraMetadata<TKey> { 
     * physical camera to the other.</p>

     *

     * @see CameraCharacteristics#LENS_DISTORTION

     * @see CaptureRequest#LENS_FOCAL_LENGTH

     * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION

     * @see CameraCharacteristics#LENS_INFO_HYPERFOCAL_DISTANCE

     * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE

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

+25 −15
Original line number Diff line number Diff line
@@ -1452,6 +1452,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 
     *   <li>{@link #CONTROL_AE_MODE_ON_ALWAYS_FLASH ON_ALWAYS_FLASH}</li>

     *   <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ON_AUTO_FLASH_REDEYE}</li>

     *   <li>{@link #CONTROL_AE_MODE_ON_EXTERNAL_FLASH ON_EXTERNAL_FLASH}</li>

     *   <li>{@link #CONTROL_AE_MODE_ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY}</li>

     * </ul>

     *

     * <p><b>Available values for this device:</b><br>
@@ -1476,6 +1477,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 
     * @see #CONTROL_AE_MODE_ON_ALWAYS_FLASH

     * @see #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE

     * @see #CONTROL_AE_MODE_ON_EXTERNAL_FLASH

     * @see #CONTROL_AE_MODE_ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY

     */

    @PublicKey

    @NonNull
@@ -3163,28 +3165,36 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 
            new Key<Float>("android.lens.filterDensity", float.class);



    /**

     * <p>The desired lens focal length; used for optical zoom.</p>

     * <p>This setting controls the physical focal length of the camera

     * device's lens. Changing the focal length changes the field of

     * view of the camera device, and is usually used for optical zoom.</p>

     * <p>Like {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} and {@link CaptureRequest#LENS_APERTURE android.lens.aperture}, this

     * setting won't be applied instantaneously, and it may take several

     * 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

     * be set to MOVING.</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>The desired lens focal length</p>

     * <p>Focal length is the distance from the optical center of the lens to the

     * focal point for a thin lens approximation of the camera optical system.

     * The definition assumes the lens is focused at infinity.</p>

     * <p>The horizontal field-of-view of the processed full frame camera outputs

     * can be derived as:</p>

     * <pre><code>fov = 2 * atan2(sw / 2, fl)

     * </code></pre>

     * <p>where:</p>

     * <ul>

     * <li><code>sw</code> is the {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} width,</li>

     * <li><code>fl</code> is {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}.</li>

     * </ul>

     * <p>Using this control to switch between lenses is not supported on most

     * devices. Starting from API level 30, the application is strongly recommended

     * to use {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} for combined optical and digital zoom. To

     * exclusively use a particular focal length lens in a logical multi-camera,

     * applications can iterate over the physical cameras exposed by the logical

     * multi-camera device via

     * {@link android.hardware.camera2.CameraCharacteristics#getPhysicalCameraIds }

     * and select the one with the desired focal length.</p>

     * <p><b>Units</b>: Millimeters</p>

     * <p><b>Range of valid values:</b><br>

     * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>

     * <p>This key is available on all devices.</p>

     *

     * @see CaptureRequest#CONTROL_ZOOM_RATIO

     * @see CaptureRequest#LENS_APERTURE

     * @see CaptureRequest#LENS_FOCUS_DISTANCE

     * @see CaptureRequest#LENS_FOCAL_LENGTH

     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS

     * @see CaptureResult#LENS_STATE

     * @see CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE

     */

    @PublicKey

    @NonNull

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

+27 −18
Original line number Diff line number Diff line
@@ -892,6 +892,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
     *   <li>{@link #CONTROL_AE_MODE_ON_ALWAYS_FLASH ON_ALWAYS_FLASH}</li>

     *   <li>{@link #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE ON_AUTO_FLASH_REDEYE}</li>

     *   <li>{@link #CONTROL_AE_MODE_ON_EXTERNAL_FLASH ON_EXTERNAL_FLASH}</li>

     *   <li>{@link #CONTROL_AE_MODE_ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY}</li>

     * </ul>

     *

     * <p><b>Available values for this device:</b><br>
@@ -916,6 +917,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
     * @see #CONTROL_AE_MODE_ON_ALWAYS_FLASH

     * @see #CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE

     * @see #CONTROL_AE_MODE_ON_EXTERNAL_FLASH

     * @see #CONTROL_AE_MODE_ON_LOW_LIGHT_BOOST_BRIGHTNESS_PRIORITY

     */

    @PublicKey

    @NonNull
@@ -3493,28 +3495,36 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
            new Key<Float>("android.lens.filterDensity", float.class);



    /**

     * <p>The desired lens focal length; used for optical zoom.</p>

     * <p>This setting controls the physical focal length of the camera

     * device's lens. Changing the focal length changes the field of

     * view of the camera device, and is usually used for optical zoom.</p>

     * <p>Like {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} and {@link CaptureRequest#LENS_APERTURE android.lens.aperture}, this

     * setting won't be applied instantaneously, and it may take several

     * 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

     * be set to MOVING.</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>The desired lens focal length</p>

     * <p>Focal length is the distance from the optical center of the lens to the

     * focal point for a thin lens approximation of the camera optical system.

     * The definition assumes the lens is focused at infinity.</p>

     * <p>The horizontal field-of-view of the processed full frame camera outputs

     * can be derived as:</p>

     * <pre><code>fov = 2 * atan2(sw / 2, fl)

     * </code></pre>

     * <p>where:</p>

     * <ul>

     * <li><code>sw</code> is the {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} width,</li>

     * <li><code>fl</code> is {@link CaptureRequest#LENS_FOCAL_LENGTH android.lens.focalLength}.</li>

     * </ul>

     * <p>Using this control to switch between lenses is not supported on most

     * devices. Starting from API level 30, the application is strongly recommended

     * to use {@link CaptureRequest#CONTROL_ZOOM_RATIO android.control.zoomRatio} for combined optical and digital zoom. To

     * exclusively use a particular focal length lens in a logical multi-camera,

     * applications can iterate over the physical cameras exposed by the logical

     * multi-camera device via

     * {@link android.hardware.camera2.CameraCharacteristics#getPhysicalCameraIds }

     * and select the one with the desired focal length.</p>

     * <p><b>Units</b>: Millimeters</p>

     * <p><b>Range of valid values:</b><br>

     * {@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths}</p>

     * <p>This key is available on all devices.</p>

     *

     * @see CaptureRequest#CONTROL_ZOOM_RATIO

     * @see CaptureRequest#LENS_APERTURE

     * @see CaptureRequest#LENS_FOCUS_DISTANCE

     * @see CaptureRequest#LENS_FOCAL_LENGTH

     * @see CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS

     * @see CaptureResult#LENS_STATE

     * @see CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE

     */

    @PublicKey

    @NonNull
@@ -3626,8 +3636,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
     * <ul>

     * <li>Fixed focus (<code>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance} == 0</code>), which means

     * {@link CaptureRequest#LENS_FOCUS_DISTANCE android.lens.focusDistance} parameter will always be 0.</li>

     * <li>Fixed focal length ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths} contains single value),

     * which means the optical zoom is not supported.</li>

     * <li>Fixed focal length ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_FOCAL_LENGTHS android.lens.info.availableFocalLengths} contains single value).</li>

     * <li>No ND filter ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_FILTER_DENSITIES android.lens.info.availableFilterDensities} contains only 0).</li>

     * <li>Fixed aperture ({@link CameraCharacteristics#LENS_INFO_AVAILABLE_APERTURES android.lens.info.availableApertures} contains single value).</li>

     * </ul>
@@ -5501,7 +5510,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
     * <p>An array of intra-frame lens intrinsic samples.</p>

     * <p>Contains an array of intra-frame {@link CameraCharacteristics#LENS_INTRINSIC_CALIBRATION android.lens.intrinsicCalibration} updates. This must

     * not be confused or compared to {@link CaptureResult#STATISTICS_OIS_SAMPLES android.statistics.oisSamples}. Although OIS could be the

     * main driver, all relevant factors such as focus distance and optical zoom must also

     * main driver, all relevant factors such as focus distance and focal length must also

     * be included. Do note that OIS samples must not be applied on top of the lens intrinsic

     * samples.

     * Support for this capture result can be queried via