NEW_API: Add auto-exposure and auto-white balance locking to the Camera.

Unhides the Camera API calls for using the auto-exposure and
auto-white balance locks. Adds documentation about the interaction
between auto-focus and the AE and AWB locks.

Change-Id: I5bf73b9dce1c93e11a17f9d3efb82db1261524c5

diff --git a/api/current.txt b/api/current.txt
index 86339f2..b2aea5b 100644 (file)
--- a/api/current.txt
+++ b/api/current.txt
@@ -8938,6 +8938,8 @@ package android.hardware {
     method public java.lang.String flatten();
     method public java.lang.String get(java.lang.String);
     method public java.lang.String getAntibanding();
+    method public boolean getAutoExposureLock();
+    method public boolean getAutoWhiteBalanceLock();
     method public java.lang.String getColorEffect();
     method public int getExposureCompensation();
     method public float getExposureCompensationStep();
@@ -8983,6 +8985,8 @@ package android.hardware {
     method public java.lang.String getWhiteBalance();
     method public int getZoom();
     method public java.util.List<java.lang.Integer> getZoomRatios();
+    method public boolean isAutoExposureLockSupported();
+    method public boolean isAutoWhiteBalanceLockSupported();
     method public boolean isSmoothZoomSupported();
     method public boolean isZoomSupported();
     method public void remove(java.lang.String);
@@ -8990,6 +8994,8 @@ package android.hardware {
     method public void set(java.lang.String, java.lang.String);
     method public void set(java.lang.String, int);
     method public void setAntibanding(java.lang.String);
+    method public void setAutoExposureLock(boolean);
+    method public void setAutoWhiteBalanceLock(boolean);
     method public void setColorEffect(java.lang.String);
     method public void setExposureCompensation(int);
     method public void setFlashMode(java.lang.String);

diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 8a42693..7d67e11 100644 (file)
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -720,8 +720,20 @@ public class Camera {
          * onAutoFocus will be called immediately with a fake value of
          * <code>success</code> set to <code>true</code>.
          *
+         * The auto-focus routine may lock auto-exposure and auto-white balance
+         * after it completes. To check for the state of these locks, use the
+         * {@link android.hardware.Camera.Parameters#getAutoExposureLock()} and
+         * {@link android.hardware.Camera.Parameters#getAutoWhiteBalanceLock()}
+         * methods. If such locking is undesirable, use
+         * {@link android.hardware.Camera.Parameters#setAutoExposureLock(boolean)}
+         * and
+         * {@link android.hardware.Camera.Parameters#setAutoWhiteBalanceLock(boolean)}
+         * to release the locks.
+         *
          * @param success true if focus was successful, false if otherwise
          * @param camera  the Camera service object
+         * @see android.hardware.Camera.Parameters#setAutoExposureLock(boolean)
+         * @see android.hardware.Camera.Parameters#setAutoWhiteBalanceLock(boolean)
          */
         void onAutoFocus(boolean success, Camera camera);
     };
@@ -747,8 +759,21 @@ public class Camera {
      * {@link android.hardware.Camera.Parameters#FLASH_MODE_OFF}, flash may be
      * fired during auto-focus, depending on the driver and camera hardware.<p>
      *
+     * The auto-focus routine may lock auto-exposure and auto-white balance
+     * after it completes. To check for the state of these locks, use the
+     * {@link android.hardware.Camera.Parameters#getAutoExposureLock()} and
+     * {@link android.hardware.Camera.Parameters#getAutoWhiteBalanceLock()}
+     * methods after the {@link AutoFocusCallback#onAutoFocus(boolean, Camera)}
+     * callback is invoked. If such locking is undesirable, use
+     * {@link android.hardware.Camera.Parameters#setAutoExposureLock(boolean)}
+     * and
+     * {@link android.hardware.Camera.Parameters#setAutoWhiteBalanceLock(boolean)}
+     * to release the locks.
+     *
      * @param cb the callback to run
      * @see #cancelAutoFocus()
+     * @see android.hardware.Camera.Parameters#setAutoExposureLock(boolean)
+     * @see android.hardware.Camera.Parameters#setAutoWhiteBalanceLock(boolean)
      */
     public final void autoFocus(AutoFocusCallback cb)
     {
@@ -763,7 +788,13 @@ public class Camera {
      * this function will return the focus position to the default.
      * If the camera does not support auto-focus, this is a no-op.
      *
+     * Canceling auto-focus will return the auto-exposure lock and auto-white
+     * balance lock to their state before {@link #autoFocus(AutoFocusCallback)}
+     * was called.
+     *
      * @see #autoFocus(Camera.AutoFocusCallback)
+     * @see android.hardware.Camera.Parameters#setAutoExposureLock(boolean)
+     * @see android.hardware.Camera.Parameters#setAutoWhiteBalanceLock(boolean)
      */
     public final void cancelAutoFocus()
     {
@@ -2562,8 +2593,6 @@ public class Camera {
          *        routine is free to run normally.
          *
          * @see #getAutoExposureLock()
-         *
-         * @hide
          */
         public void setAutoExposureLock(boolean toggle) {
             set(KEY_AUTO_EXPOSURE_LOCK, toggle ? TRUE : FALSE);
@@ -2583,7 +2612,6 @@ public class Camera {
          *
          * @see #setAutoExposureLock(boolean)
          *
-         * @hide
          */
         public boolean getAutoExposureLock() {
             String str = get(KEY_AUTO_EXPOSURE_LOCK);
@@ -2598,7 +2626,6 @@ public class Camera {
          * @return true if auto-exposure lock is supported.
          * @see #setAutoExposureLock(boolean)
          *
-         * @hide
          */
         public boolean isAutoExposureLockSupported() {
             String str = get(KEY_AUTO_EXPOSURE_LOCK_SUPPORTED);
@@ -2645,8 +2672,6 @@ public class Camera {
          *        auto-white balance routine is free to run normally.
          *
          * @see #getAutoWhiteBalanceLock()
-         *
-         * @hide
          */
         public void setAutoWhiteBalanceLock(boolean toggle) {
             set(KEY_AUTO_WHITEBALANCE_LOCK, toggle ? TRUE : FALSE);
@@ -2668,7 +2693,6 @@ public class Camera {
          *
          * @see #setAutoWhiteBalanceLock(boolean)
          *
-         * @hide
          */
         public boolean getAutoWhiteBalanceLock() {
             String str = get(KEY_AUTO_WHITEBALANCE_LOCK);
@@ -2683,7 +2707,6 @@ public class Camera {
          * @return true if auto-white balance lock is supported.
          * @see #setAutoWhiteBalanceLock(boolean)
          *
-         * @hide
          */
         public boolean isAutoWhiteBalanceLockSupported() {
             String str = get(KEY_AUTO_WHITEBALANCE_LOCK_SUPPORTED);