diff options
| -rw-r--r-- | api/current.txt | 1 | ||||
| -rw-r--r-- | api/system-current.txt | 1 | ||||
| -rw-r--r-- | core/java/android/hardware/camera2/CameraMetadata.java | 13 | ||||
| -rw-r--r-- | core/java/android/hardware/camera2/CaptureRequest.java | 22 | ||||
| -rw-r--r-- | core/java/android/hardware/camera2/CaptureResult.java | 58 |
5 files changed, 87 insertions, 8 deletions
diff --git a/api/current.txt b/api/current.txt index 1abcdb1fe0c2..c5d63fe0fa39 100644 --- a/api/current.txt +++ b/api/current.txt @@ -12882,6 +12882,7 @@ package android.hardware.camera2 { field public static final int CONTROL_AE_MODE_ON_ALWAYS_FLASH = 3; // 0x3 field public static final int CONTROL_AE_MODE_ON_AUTO_FLASH = 2; // 0x2 field public static final int CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE = 4; // 0x4 + field public static final int CONTROL_AE_PRECAPTURE_TRIGGER_CANCEL = 2; // 0x2 field public static final int CONTROL_AE_PRECAPTURE_TRIGGER_IDLE = 0; // 0x0 field public static final int CONTROL_AE_PRECAPTURE_TRIGGER_START = 1; // 0x1 field public static final int CONTROL_AE_STATE_CONVERGED = 2; // 0x2 diff --git a/api/system-current.txt b/api/system-current.txt index d971ce7a4b1a..c14cde55568d 100644 --- a/api/system-current.txt +++ b/api/system-current.txt @@ -13152,6 +13152,7 @@ package android.hardware.camera2 { field public static final int CONTROL_AE_MODE_ON_ALWAYS_FLASH = 3; // 0x3 field public static final int CONTROL_AE_MODE_ON_AUTO_FLASH = 2; // 0x2 field public static final int CONTROL_AE_MODE_ON_AUTO_FLASH_REDEYE = 4; // 0x4 + field public static final int CONTROL_AE_PRECAPTURE_TRIGGER_CANCEL = 2; // 0x2 field public static final int CONTROL_AE_PRECAPTURE_TRIGGER_IDLE = 0; // 0x0 field public static final int CONTROL_AE_PRECAPTURE_TRIGGER_START = 1; // 0x1 field public static final int CONTROL_AE_STATE_CONVERGED = 2; // 0x2 diff --git a/core/java/android/hardware/camera2/CameraMetadata.java b/core/java/android/hardware/camera2/CameraMetadata.java index af7d3650df68..926bb73e381d 100644 --- a/core/java/android/hardware/camera2/CameraMetadata.java +++ b/core/java/android/hardware/camera2/CameraMetadata.java @@ -1029,6 +1029,14 @@ public abstract class CameraMetadata<TKey> { */ public static final int CONTROL_AE_PRECAPTURE_TRIGGER_START = 1; + /** + * <p>The camera device will cancel any currently active or completed + * precapture metering sequence, the auto-exposure routine will return to its + * initial state.</p> + * @see CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER + */ + public static final int CONTROL_AE_PRECAPTURE_TRIGGER_CANCEL = 2; + // // Enumeration values for CaptureRequest#CONTROL_AF_MODE // @@ -2143,7 +2151,10 @@ public abstract class CameraMetadata<TKey> { * <p>AE has been asked to do a precapture sequence * and is currently executing it.</p> * <p>Precapture can be triggered through setting - * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} to START.</p> + * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} to START. Currently + * active and completed (if it causes camera device internal AE lock) precapture + * metering sequence can be canceled through setting + * {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} to CANCEL.</p> * <p>Once PRECAPTURE completes, AE will transition to CONVERGED * or FLASH_REQUIRED as appropriate. This is a transient * state, the camera device may skip reporting this state in diff --git a/core/java/android/hardware/camera2/CaptureRequest.java b/core/java/android/hardware/camera2/CaptureRequest.java index a40d47a85966..038d776e5ab8 100644 --- a/core/java/android/hardware/camera2/CaptureRequest.java +++ b/core/java/android/hardware/camera2/CaptureRequest.java @@ -730,7 +730,14 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * ({@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}) and sensitivity ({@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}) * parameters. The flash may be fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} * is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the - * {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed.</p> + * {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed. + * Similarly, AE precapture trigger CANCEL has no effect when AE is already locked.</p> + * <p>When an AE precapture sequence is triggered, AE unlock will not be able to unlock + * the AE if AE is locked by the camera device internally during precapture metering + * sequence In other words, submitting requests with AE unlock has no effect for an + * ongoing precapture metering sequence. Otherwise, the precapture metering sequence + * will never succeed in a sequence of preview requests where AE lock is always set + * to <code>false</code>.</p> * <p>Since the camera device has a pipeline of in-flight requests, the settings that * get locked do not necessarily correspond to the settings that were present in the * latest capture result received from the camera device, since additional captures @@ -875,6 +882,11 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * included at all in the request settings. When included and * set to START, the camera device will trigger the auto-exposure (AE) * precapture metering sequence.</p> + * <p>When set to CANCEL, the camera device will cancel any active + * precapture metering trigger, and return to its initial AE state. + * If a precapture metering sequence is already completed, and the camera + * device has implicitly locked the AE for subsequent still capture, the + * CANCEL trigger will unlock the AE and return to its initial AE state.</p> * <p>The precapture sequence should be triggered before starting a * high-quality still capture for final metering decisions to * be made, and for firing pre-capture flash pulses to estimate @@ -890,7 +902,11 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * submitted. To ensure that the AE routine restarts normal scan, the application should * submit a request with <code>{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} == true</code>, followed by a request * with <code>{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} == false</code>, if the application decides not to submit a - * still capture request after the precapture sequence completes.</p> + * still capture request after the precapture sequence completes. Alternatively, for + * API level 23 or newer devices, the CANCEL can be used to unlock the camera device + * internally locked AE if the application doesn't submit a still capture request after + * the AE precapture trigger. Note that, the CANCEL was added in API level 23, and must not + * be used in devices that have earlier API levels.</p> * <p>The exact effect of auto-exposure (AE) precapture trigger * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition @@ -903,6 +919,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * <ul> * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE IDLE}</li> * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_START START}</li> + * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_CANCEL CANCEL}</li> * </ul></p> * <p><b>Optional</b> - This value may be {@code null} on some devices.</p> * <p><b>Limited capability</b> - @@ -915,6 +932,7 @@ public final class CaptureRequest extends CameraMetadata<CaptureRequest.Key<?>> * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE * @see #CONTROL_AE_PRECAPTURE_TRIGGER_START + * @see #CONTROL_AE_PRECAPTURE_TRIGGER_CANCEL */ @PublicKey public static final Key<Integer> CONTROL_AE_PRECAPTURE_TRIGGER = diff --git a/core/java/android/hardware/camera2/CaptureResult.java b/core/java/android/hardware/camera2/CaptureResult.java index 810d0f6fe7ba..6f6651d54c42 100644 --- a/core/java/android/hardware/camera2/CaptureResult.java +++ b/core/java/android/hardware/camera2/CaptureResult.java @@ -581,7 +581,14 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * ({@link CaptureRequest#SENSOR_EXPOSURE_TIME android.sensor.exposureTime}) and sensitivity ({@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity}) * parameters. The flash may be fired if the {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} * is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the - * {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed.</p> + * {@link CaptureRequest#CONTROL_AE_MODE android.control.aeMode} is ON_ALWAYS_FLASH, the scene may become overexposed. + * Similarly, AE precapture trigger CANCEL has no effect when AE is already locked.</p> + * <p>When an AE precapture sequence is triggered, AE unlock will not be able to unlock + * the AE if AE is locked by the camera device internally during precapture metering + * sequence In other words, submitting requests with AE unlock has no effect for an + * ongoing precapture metering sequence. Otherwise, the precapture metering sequence + * will never succeed in a sequence of preview requests where AE lock is always set + * to <code>false</code>.</p> * <p>Since the camera device has a pipeline of in-flight requests, the settings that * get locked do not necessarily correspond to the settings that were present in the * latest capture result received from the camera device, since additional captures @@ -726,6 +733,11 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * included at all in the request settings. When included and * set to START, the camera device will trigger the auto-exposure (AE) * precapture metering sequence.</p> + * <p>When set to CANCEL, the camera device will cancel any active + * precapture metering trigger, and return to its initial AE state. + * If a precapture metering sequence is already completed, and the camera + * device has implicitly locked the AE for subsequent still capture, the + * CANCEL trigger will unlock the AE and return to its initial AE state.</p> * <p>The precapture sequence should be triggered before starting a * high-quality still capture for final metering decisions to * be made, and for firing pre-capture flash pulses to estimate @@ -741,7 +753,11 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * submitted. To ensure that the AE routine restarts normal scan, the application should * submit a request with <code>{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} == true</code>, followed by a request * with <code>{@link CaptureRequest#CONTROL_AE_LOCK android.control.aeLock} == false</code>, if the application decides not to submit a - * still capture request after the precapture sequence completes.</p> + * still capture request after the precapture sequence completes. Alternatively, for + * API level 23 or newer devices, the CANCEL can be used to unlock the camera device + * internally locked AE if the application doesn't submit a still capture request after + * the AE precapture trigger. Note that, the CANCEL was added in API level 23, and must not + * be used in devices that have earlier API levels.</p> * <p>The exact effect of auto-exposure (AE) precapture trigger * depends on the current AE mode and state; see * {@link CaptureResult#CONTROL_AE_STATE android.control.aeState} for AE precapture state transition @@ -754,6 +770,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <ul> * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE IDLE}</li> * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_START START}</li> + * <li>{@link #CONTROL_AE_PRECAPTURE_TRIGGER_CANCEL CANCEL}</li> * </ul></p> * <p><b>Optional</b> - This value may be {@code null} on some devices.</p> * <p><b>Limited capability</b> - @@ -766,6 +783,7 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL * @see #CONTROL_AE_PRECAPTURE_TRIGGER_IDLE * @see #CONTROL_AE_PRECAPTURE_TRIGGER_START + * @see #CONTROL_AE_PRECAPTURE_TRIGGER_CANCEL */ @PublicKey public static final Key<Integer> CONTROL_AE_PRECAPTURE_TRIGGER = @@ -898,11 +916,29 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <td align="center">Ready for high-quality capture</td> * </tr> * <tr> - * <td align="center">Any state</td> + * <td align="center">LOCKED</td> + * <td align="center">aeLock is ON and aePrecaptureTrigger is START</td> + * <td align="center">LOCKED</td> + * <td align="center">Precapture trigger is ignored when AE is already locked</td> + * </tr> + * <tr> + * <td align="center">LOCKED</td> + * <td align="center">aeLock is ON and aePrecaptureTrigger is CANCEL</td> + * <td align="center">LOCKED</td> + * <td align="center">Precapture trigger is ignored when AE is already locked</td> + * </tr> + * <tr> + * <td align="center">Any state (excluding LOCKED)</td> * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START</td> * <td align="center">PRECAPTURE</td> * <td align="center">Start AE precapture metering sequence</td> * </tr> + * <tr> + * <td align="center">Any state (excluding LOCKED)</td> + * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is CANCEL</td> + * <td align="center">INACTIVE</td> + * <td align="center">Currently active precapture metering sequence is canceled</td> + * </tr> * </tbody> * </table> * <p>For the above table, the camera device may skip reporting any state changes that happen @@ -928,18 +964,30 @@ public class CaptureResult extends CameraMetadata<CaptureResult.Key<?>> { * <td align="center">Values are already good, transient states are skipped by camera device.</td> * </tr> * <tr> - * <td align="center">Any state</td> + * <td align="center">Any state (excluding LOCKED)</td> * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START, sequence done</td> * <td align="center">FLASH_REQUIRED</td> * <td align="center">Converged but too dark w/o flash after a precapture sequence, transient states are skipped by camera device.</td> * </tr> * <tr> - * <td align="center">Any state</td> + * <td align="center">Any state (excluding LOCKED)</td> * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is START, sequence done</td> * <td align="center">CONVERGED</td> * <td align="center">Converged after a precapture sequence, transient states are skipped by camera device.</td> * </tr> * <tr> + * <td align="center">Any state (excluding LOCKED)</td> + * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is CANCEL, converged</td> + * <td align="center">FLASH_REQUIRED</td> + * <td align="center">Converged but too dark w/o flash after a precapture sequence is canceled, transient states are skipped by camera device.</td> + * </tr> + * <tr> + * <td align="center">Any state (excluding LOCKED)</td> + * <td align="center">{@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER android.control.aePrecaptureTrigger} is CANCEL, converged</td> + * <td align="center">CONVERGED</td> + * <td align="center">Converged after a precapture sequenceis canceled, transient states are skipped by camera device.</td> + * </tr> + * <tr> * <td align="center">CONVERGED</td> * <td align="center">Camera device finished AE scan</td> * <td align="center">FLASH_REQUIRED</td> |