Add auto-white balance locking to the Camera API.

Adds a new camera parameter for locking auto-white balance to its
current value. Also adds a function for checking if auto-white balance
lock is supported by the current platform. Lock semantics match that
of the auto-exposure lock.

Hidden for now.

Change-Id: Id59339a4be84d55c1b0b8473d765b6aa765999b2

1 files changed, 115 insertions, 18 deletions

diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 6d955e7..d5c4ace 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -1181,6 +1181,8 @@ public class Camera {
         private static final String KEY_EXPOSURE_COMPENSATION_STEP = "exposure-compensation-step";
         private static final String KEY_AUTO_EXPOSURE_LOCK = "auto-exposure-lock";
         private static final String KEY_AUTO_EXPOSURE_LOCK_SUPPORTED = "auto-exposure-lock-supported";
+        private static final String KEY_AUTO_WHITEBALANCE_LOCK = "auto-whitebalance-lock";
+        private static final String KEY_AUTO_WHITEBALANCE_LOCK_SUPPORTED = "auto-whitebalance-lock-supported";
         private static final String KEY_METERING_AREAS = "metering-areas";
         private static final String KEY_MAX_NUM_METERING_AREAS = "max-num-metering-areas";
         private static final String KEY_ZOOM = "zoom";
@@ -2468,37 +2470,47 @@ public class Camera {
         }
 
         /**
-         * Sets the auto-exposure lock state. Applications should check
-         * {@link #isAutoExposureLockSupported} before using this method.
+         * <p>Sets the auto-exposure lock state. Applications should check
+         * {@link #isAutoExposureLockSupported} before using this method.</p>
          *
-         * If set to true, the camera auto-exposure routine will pause until the
-         * lock is set to false. Exposure compensation settings changes will
-         * still take effect while auto-exposure is locked. Stopping preview
-         * with {@link #stopPreview()}, or triggering still image capture with
-         * {@link #takePicture(Camera.ShutterCallback, Camera.PictureCallback,
-         * Camera.PictureCallback)}, will automatically set the lock to
-         * false. However, the lock can be re-enabled before preview is
-         * re-started to keep the same AE parameters. Exposure compensation, in
-         * conjunction with re-enabling the AE lock after each still capture,
-         * can be used to capture an exposure-bracketed burst of images, for
-         * example. Auto-exposure state, including the lock state, will not be
+         * <p>If set to true, the camera auto-exposure routine will immediately
+         * pause until the lock is set to false. Exposure compensation settings
+         * changes will still take effect while auto-exposure is locked.</p>
+         *
+         * <p>If auto-exposure is already locked, setting this to true again has
+         * no effect (the driver will not recalculate exposure values).</p>
+         *
+         * <p>Stopping preview with {@link #stopPreview()}, or triggering still
+         * image capture with {@link #takePicture(Camera.ShutterCallback,
+         * Camera.PictureCallback, Camera.PictureCallback)}, will automatically
+         * set the lock to false. However, the lock can be re-enabled before
+         * preview is re-started to keep the same AE parameters.</p>
+         *
+         * <p>Exposure compensation, in conjunction with re-enabling the AE and
+         * AWB locks after each still capture, can be used to capture an
+         * exposure-bracketed burst of images, for example.</p>
+         *
+         * <p>Auto-exposure state, including the lock state, will not be
          * maintained after camera {@link #release()} is called.  Locking
          * auto-exposure after {@link #open()} but before the first call to
          * {@link #startPreview()} will not allow the auto-exposure routine to
-         * run at all, and may result in severely over- or under-exposed images.
+         * run at all, and may result in severely over- or under-exposed
+         * images.</p>
          *
-         * The driver may also independently lock auto-exposure after auto-focus
-         * completes. If this is undesirable, be sure to always set the
-         * auto-exposure lock to false after the
+         * <p>The driver may also independently lock auto-exposure after
+         * auto-focus completes. If this is undesirable, be sure to always set
+         * the auto-exposure lock to false after the
          * {@link AutoFocusCallback#onAutoFocus(boolean, Camera)} callback is
          * received. The {@link #getAutoExposureLock()} method can be used after
          * the callback to determine if the camera has locked auto-exposure
-         * independently.
+         * independently.</p>
          *
          * @param toggle new state of the auto-exposure lock. True means that
          *        auto-exposure is locked, false means that the auto-exposure
          *        routine is free to run normally.
          *
+         * @see #getAutoExposureLock()
+         *
          * @hide
          */
         public void setAutoExposureLock(boolean toggle) {
@@ -2542,6 +2554,91 @@ public class Camera {
         }
 
         /**
+         * <p>Sets the auto-white balance lock state. Applications should check
+         * {@link #isAutoWhiteBalanceLockSupported} before using this
+         * method.</p>
+         *
+         * <p>If set to true, the camera auto-white balance routine will
+         * immediately pause until the lock is set to false.</p>
+         *
+         * <p>If auto-white balance is already locked, setting this to true
+         * again has no effect (the driver will not recalculate white balance
+         * values).</p>
+         *
+         * <p>Stopping preview with {@link #stopPreview()}, or triggering still
+         * image capture with {@link #takePicture(Camera.ShutterCallback,
+         * Camera.PictureCallback, Camera.PictureCallback)}, will automatically
+         * set the lock to false. However, the lock can be re-enabled before
+         * preview is re-started to keep the same white balance parameters.</p>
+         *
+         * <p>Exposure compensation, in conjunction with re-enabling the AE and
+         * AWB locks after each still capture, can be used to capture an
+         * exposure-bracketed burst of images, for example. Auto-white balance
+         * state, including the lock state, will not be maintained after camera
+         * {@link #release()} is called.  Locking auto-white balance after
+         * {@link #open()} but before the first call to {@link #startPreview()}
+         * will not allow the auto-white balance routine to run at all, and may
+         * result in severely incorrect color in captured images.</p>
+         *
+         * <p>The driver may also independently lock auto-white balance after
+         * auto-focus completes. If this is undesirable, be sure to always set
+         * the auto-white balance lock to false after the
+         * {@link AutoFocusCallback#onAutoFocus(boolean, Camera)} callback is
+         * received. The {@link #getAutoWhiteBalanceLock()} method can be used
+         * after the callback to determine if the camera has locked auto-white
+         * balance independently.</p>
+         *
+         * @param toggle new state of the auto-white balance lock. True means
+         *        that auto-white balance is locked, false means that the
+         *        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);
+        }
+
+        /**
+         * Gets the state of the auto-white balance lock. Applications should
+         * check {@link #isAutoWhiteBalanceLockSupported} before using this
+         * method. See {@link #setAutoWhiteBalanceLock} for details about the
+         * lock.
+         *
+         * @return State of the auto-white balance lock. Returns true if
+         *         auto-white balance is currently locked, and false
+         *         otherwise. The auto-white balance lock may be independently
+         *         enabled by the camera subsystem when auto-focus has
+         *         completed. This method can be used after the
+         *         {@link AutoFocusCallback#onAutoFocus(boolean, Camera)}
+         *         callback to determine if the camera has locked AWB.
+         *
+         * @see #setAutoWhiteBalanceLock(boolean)
+         *
+         * @hide
+         */
+        public boolean getAutoWhiteBalanceLock() {
+            String str = get(KEY_AUTO_WHITEBALANCE_LOCK);
+            return TRUE.equals(str);
+        }
+
+        /**
+         * Returns true if auto-white balance locking is supported. Applications
+         * should call this before trying to lock auto-white balance. See
+         * {@link #setAutoWhiteBalanceLock} for details about the lock.
+         *
+         * @return true if auto-white balance lock is supported.
+         * @see #setAutoWhiteBalanceLock(boolean)
+         *
+         * @hide
+         */
+        public boolean isAutoWhiteBalanceLockSupported() {
+            String str = get(KEY_AUTO_WHITEBALANCE_LOCK_SUPPORTED);
+            return TRUE.equals(str);
+        }
+
+        /**
          * Gets current zoom value. This also works when smooth zoom is in
          * progress. Applications should check {@link #isZoomSupported} before
          * using this method.