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

Commit 61aaa326 authored by Shuzhen Wang's avatar Shuzhen Wang
Browse files

Camera: Add support for dynamic physical camera switch 

- Add activePhysicalId metadata tag for logical camera to indicate current
active physical camera backing logical camera.
- Clarify synchronization between optical and digital zoom controls.
- Specify metadata tags behaviors when active physical camera switches.

Test: Camera CTS for Pixel 3 logical camera
Bug: 77915333
Change-Id: I0cdb523587e8eef324cb1043914c774824d71159
parent e6f2eefc

api/current.txt

+1 −0
Original line number Diff line number Diff line
@@ -17122,6 +17122,7 @@ package android.hardware.camera2 { 
    field public static final android.hardware.camera2.CaptureResult.Key<float[]> LENS_POSE_TRANSLATION;

    field public static final deprecated android.hardware.camera2.CaptureResult.Key<float[]> LENS_RADIAL_DISTORTION;

    field public static final android.hardware.camera2.CaptureResult.Key<java.lang.Integer> LENS_STATE;

    field public static final android.hardware.camera2.CaptureResult.Key<java.lang.String> LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID;

    field public static final android.hardware.camera2.CaptureResult.Key<java.lang.Integer> NOISE_REDUCTION_MODE;

    field public static final android.hardware.camera2.CaptureResult.Key<java.lang.Float> REPROCESS_EFFECTIVE_EXPOSURE_FACTOR;

    field public static final android.hardware.camera2.CaptureResult.Key<java.lang.Byte> REQUEST_PIPELINE_DEPTH;

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

+5 −5
Original line number Diff line number Diff line
@@ -3722,12 +3722,12 @@ public final class CameraCharacteristics extends CameraMetadata<CameraCharacteri 


    /**

     * <p>String containing the ids of the underlying physical cameras.</p>

     * <p>For a logical camera, this is concatenation of all underlying physical camera ids.

     * The null terminator for physical camera id must be preserved so that the whole string

     * can be tokenized using '\0' to generate list of physical camera ids.</p>

     * <p>For example, if the physical camera ids of the logical camera are "2" and "3", the

     * <p>For a logical camera, this is concatenation of all underlying physical camera IDs.

     * The null terminator for physical camera ID must be preserved so that the whole string

     * can be tokenized using '\0' to generate list of physical camera IDs.</p>

     * <p>For example, if the physical camera IDs of the logical camera are "2" and "3", the

     * value of this tag will be ['2', '\0', '3', '\0'].</p>

     * <p>The number of physical camera ids must be no less than 2.</p>

     * <p>The number of physical camera IDs must be no less than 2.</p>

     * <p><b>Units</b>: UTF-8 null-terminated string</p>

     * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>

     * <p><b>Limited capability</b> -

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

+80 −1
Original line number Diff line number Diff line
@@ -428,6 +428,10 @@ public abstract class CameraMetadata<TKey> { 
     * <p>If this is supported, {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap} will

     * additionally return a min frame duration that is greater than

     * zero for each supported size-format combination.</p>

     * <p>For camera devices with LOGICAL_MULTI_CAMERA capability, when the underlying active

     * physical camera switches, exposureTime, sensitivity, and lens properties may change

     * even if AE/AF is locked. However, the overall auto exposure and auto focus experience

     * for users will be consistent. Refer to LOGICAL_MULTI_CAMERA capability for details.</p>

     *

     * @see CaptureRequest#BLACK_LEVEL_LOCK

     * @see CaptureRequest#CONTROL_AE_LOCK
@@ -485,6 +489,10 @@ public abstract class CameraMetadata<TKey> { 
     * will accurately report the values applied by AWB in the result.</p>

     * <p>A given camera device may also support additional post-processing

     * controls, but this capability only covers the above list of controls.</p>

     * <p>For camera devices with LOGICAL_MULTI_CAMERA capability, when underlying active

     * physical camera switches, tonemap, white balance, and shading map may change even if

     * awb is locked. However, the overall post-processing experience for users will be

     * consistent. Refer to LOGICAL_MULTI_CAMERA capability for details.</p>

     *

     * @see CaptureRequest#COLOR_CORRECTION_ABERRATION_MODE

     * @see CameraCharacteristics#COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES
@@ -847,7 +855,7 @@ public abstract class CameraMetadata<TKey> { 
     * </li>

     * <li>The SENSOR_INFO_TIMESTAMP_SOURCE of the logical device and physical devices must be

     *   the same.</li>

     * <li>The logical camera device must be LIMITED or higher device.</li>

     * <li>The logical camera must be LIMITED or higher device.</li>

     * </ul>

     * <p>Both the logical camera device and its underlying physical devices support the

     * mandatory stream combinations required for their device levels.</p>
@@ -867,13 +875,84 @@ public abstract class CameraMetadata<TKey> { 
     * <p>Using physical streams in place of a logical stream of the same size and format will

     * not slow down the frame rate of the capture, as long as the minimum frame duration

     * of the physical and logical streams are the same.</p>

     * <p>A logical camera device's dynamic metadata may contain

     * {@link CaptureResult#LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID android.logicalMultiCamera.activePhysicalId} to notify the application of the current

     * active physical camera Id. An active physical camera is the physical camera from which

     * the logical camera's main image data outputs (YUV or RAW) and metadata come from.

     * In addition, this serves as an indication which physical camera is used to output to

     * a RAW stream, or in case only physical cameras support RAW, which physical RAW stream

     * the application should request.</p>

     * <p>Logical camera's static metadata tags below describe the default active physical

     * camera. An active physical camera is default if it's used when application directly

     * uses requests built from a template. All templates will default to the same active

     * physical camera.</p>

     * <ul>

     * <li>{@link CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE android.sensor.info.sensitivityRange}</li>

     * <li>{@link CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT android.sensor.info.colorFilterArrangement}</li>

     * <li>{@link CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE android.sensor.info.exposureTimeRange}</li>

     * <li>{@link CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION android.sensor.info.maxFrameDuration}</li>

     * <li>{@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize}</li>

     * <li>{@link CameraCharacteristics#SENSOR_INFO_WHITE_LEVEL android.sensor.info.whiteLevel}</li>

     * <li>{@link CameraCharacteristics#SENSOR_INFO_LENS_SHADING_APPLIED android.sensor.info.lensShadingApplied}</li>

     * <li>{@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1 android.sensor.referenceIlluminant1}</li>

     * <li>{@link CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT2 android.sensor.referenceIlluminant2}</li>

     * <li>{@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1 android.sensor.calibrationTransform1}</li>

     * <li>{@link CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2 android.sensor.calibrationTransform2}</li>

     * <li>{@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM1 android.sensor.colorTransform1}</li>

     * <li>{@link CameraCharacteristics#SENSOR_COLOR_TRANSFORM2 android.sensor.colorTransform2}</li>

     * <li>{@link CameraCharacteristics#SENSOR_FORWARD_MATRIX1 android.sensor.forwardMatrix1}</li>

     * <li>{@link CameraCharacteristics#SENSOR_FORWARD_MATRIX2 android.sensor.forwardMatrix2}</li>

     * <li>{@link CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN android.sensor.blackLevelPattern}</li>

     * <li>{@link CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY android.sensor.maxAnalogSensitivity}</li>

     * <li>{@link CameraCharacteristics#SENSOR_OPTICAL_BLACK_REGIONS android.sensor.opticalBlackRegions}</li>

     * <li>{@link CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES android.sensor.availableTestPatternModes}</li>

     * <li>{@link CameraCharacteristics#LENS_INFO_HYPERFOCAL_DISTANCE android.lens.info.hyperfocalDistance}</li>

     * <li>{@link CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE android.lens.info.minimumFocusDistance}</li>

     * <li>{@link CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION android.lens.info.focusDistanceCalibration}</li>

     * <li>{@link CameraCharacteristics#LENS_POSE_ROTATION android.lens.poseRotation}</li>

     * <li>{@link CameraCharacteristics#LENS_POSE_TRANSLATION android.lens.poseTranslation}</li>

     * <li>{@link CameraCharacteristics#LENS_INTRINSIC_CALIBRATION android.lens.intrinsicCalibration}</li>

     * <li>{@link CameraCharacteristics#LENS_POSE_REFERENCE android.lens.poseReference}</li>

     * <li>{@link CameraCharacteristics#LENS_DISTORTION android.lens.distortion}</li>

     * </ul>

     * <p>To maintain backward compatibility, the capture request and result metadata tags

     * required for basic camera functionalities will be solely based on the

     * logical camera capabiltity. Other request and result metadata tags, on the other

     * hand, will be based on current active physical camera. For example, the physical

     * cameras' sensor sensitivity and lens capability could be different from each other.

     * So when the application manually controls sensor exposure time/gain, or does manual

     * focus control, it must checks the current active physical camera's exposure, gain,

     * and focus distance range.</p>

     *

     * @see CameraCharacteristics#LENS_DISTORTION

     * @see CameraCharacteristics#LENS_INFO_FOCUS_DISTANCE_CALIBRATION

     * @see CameraCharacteristics#LENS_INFO_HYPERFOCAL_DISTANCE

     * @see CameraCharacteristics#LENS_INFO_MINIMUM_FOCUS_DISTANCE

     * @see CameraCharacteristics#LENS_INTRINSIC_CALIBRATION

     * @see CameraCharacteristics#LENS_POSE_REFERENCE

     * @see CameraCharacteristics#LENS_POSE_ROTATION

     * @see CameraCharacteristics#LENS_POSE_TRANSLATION

     * @see CaptureResult#LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID

     * @see CameraCharacteristics#LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE

     * @see CameraCharacteristics#SENSOR_AVAILABLE_TEST_PATTERN_MODES

     * @see CameraCharacteristics#SENSOR_BLACK_LEVEL_PATTERN

     * @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM1

     * @see CameraCharacteristics#SENSOR_CALIBRATION_TRANSFORM2

     * @see CameraCharacteristics#SENSOR_COLOR_TRANSFORM1

     * @see CameraCharacteristics#SENSOR_COLOR_TRANSFORM2

     * @see CameraCharacteristics#SENSOR_FORWARD_MATRIX1

     * @see CameraCharacteristics#SENSOR_FORWARD_MATRIX2

     * @see CameraCharacteristics#SENSOR_INFO_COLOR_FILTER_ARRANGEMENT

     * @see CameraCharacteristics#SENSOR_INFO_EXPOSURE_TIME_RANGE

     * @see CameraCharacteristics#SENSOR_INFO_LENS_SHADING_APPLIED

     * @see CameraCharacteristics#SENSOR_INFO_MAX_FRAME_DURATION

     * @see CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE

     * @see CameraCharacteristics#SENSOR_INFO_SENSITIVITY_RANGE

     * @see CameraCharacteristics#SENSOR_INFO_WHITE_LEVEL

     * @see CameraCharacteristics#SENSOR_MAX_ANALOG_SENSITIVITY

     * @see CameraCharacteristics#SENSOR_OPTICAL_BLACK_REGIONS

     * @see CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT1

     * @see CameraCharacteristics#SENSOR_REFERENCE_ILLUMINANT2

     * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES

     */

    public static final int REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA = 11;

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

+0 −1
Original line number Diff line number Diff line
@@ -2146,7 +2146,6 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> 
    /**

     * <p>32 characters describing GPS algorithm to

     * include in EXIF.</p>

     * <p><b>Units</b>: UTF-8 null-terminated string</p>

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

     * @hide

     */

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

+17 −1
Original line number Diff line number Diff line
@@ -2470,7 +2470,6 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
    /**

     * <p>32 characters describing GPS algorithm to

     * include in EXIF.</p>

     * <p><b>Units</b>: UTF-8 null-terminated string</p>

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

     * @hide

     */
@@ -4637,6 +4636,23 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { 
    public static final Key<Float> REPROCESS_EFFECTIVE_EXPOSURE_FACTOR =

            new Key<Float>("android.reprocess.effectiveExposureFactor", float.class);



    /**

     * <p>String containing the ID of the underlying active physical camera.</p>

     * <p>The ID of the active physical camera that's backing the logical camera. All camera

     * streams and metadata that are not physical camera specific will be originating from this

     * physical camera. This must be one of valid physical IDs advertised in the physicalIds

     * static tag.</p>

     * <p>For a logical camera made up of physical cameras where each camera's lenses have

     * different characteristics, the camera device may choose to switch between the physical

     * cameras when application changes FOCAL_LENGTH or SCALER_CROP_REGION.

     * At the time of lens switch, this result metadata reflects the new active physical camera

     * ID.</p>

     * <p><b>Optional</b> - This value may be {@code null} on some devices.</p>

     */

    @PublicKey

    public static final Key<String> LOGICAL_MULTI_CAMERA_ACTIVE_PHYSICAL_ID =

            new Key<String>("android.logicalMultiCamera.activePhysicalId", String.class);



    /**

     * <p>Mode of operation for the lens distortion correction block.</p>

     * <p>The lens distortion correction block attempts to improve image quality by fixing