From d9c2601afa46811bcb1345963d38010690981a01 Mon Sep 17 00:00:00 2001 From: Eino-Ville Talvala Date: Fri, 13 May 2011 10:19:59 -0700 Subject: [PATCH] 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 --- core/java/android/hardware/Camera.java | 133 +++++++++++++++++++++---- include/camera/CameraParameters.h | 59 ++++++++--- libs/camera/CameraParameters.cpp | 2 + 3 files changed, 161 insertions(+), 33 deletions(-) diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java index 6d955e72f1f18..d5c4aceb6875b 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. + *

Sets the auto-exposure lock state. Applications should check + * {@link #isAutoExposureLockSupported} before using this method.

* - * 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 + *

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.

+ * + *

If auto-exposure is already locked, setting this to true again has + * no effect (the driver will not recalculate exposure values).

+ * + *

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 and + * AWB locks 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 * 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.

* - * 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 + *

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.

* * @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) { @@ -2541,6 +2553,91 @@ public class Camera { return TRUE.equals(str); } + /** + *

Sets the auto-white balance lock state. Applications should check + * {@link #isAutoWhiteBalanceLockSupported} before using this + * method.

+ * + *

If set to true, the camera auto-white balance routine will + * immediately pause until the lock is set to false.

+ * + *

If auto-white balance is already locked, setting this to true + * again has no effect (the driver will not recalculate white balance + * values).

+ * + *

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.

+ * + *

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.

+ * + *

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.

+ * + * @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 diff --git a/include/camera/CameraParameters.h b/include/camera/CameraParameters.h index 513239f55424a..dc5fc84c6c8ae 100644 --- a/include/camera/CameraParameters.h +++ b/include/camera/CameraParameters.h @@ -309,25 +309,54 @@ public: // 0.3333, EV is -2. // Example value: "0.333333333" or "0.5". Read only. static const char KEY_EXPOSURE_COMPENSATION_STEP[]; - // The state of the auto-exposure lock. "true" means that auto-exposure is - // locked to its current value and will not change. "false" means the - // auto-exposure routine is free to change exposure settings. Changing - // exposure compensation settings will still affect the exposure settings - // while auto-exposure is locked. Stopping preview or taking a still image - // will release the lock. However, the lock can be re-enabled prior to - // preview being re-started, to keep the exposure values from the previous - // lock. In conjunction with exposure compensation, this allows for - // capturing multi-exposure brackets with known relative exposure - // values. Locking auto-exposure after open but before the first cal to - // startPreview may result in severly over- or under-exposed images. The - // driver may independently enable the AE lock after auto-focus - // completes. If it does so, this key must have its value updated to reflect - // the lock's existence. Applications are free to release such a lock, to - // re-enable AE without restarting preview. + // The state of the auto-exposure lock. "true" means that + // auto-exposure is locked to its current value and will not + // change. "false" means the auto-exposure routine is free to + // change exposure values. If auto-exposure is already locked, + // setting this to true again has no effect (the driver will not + // recalculate exposure values). Changing exposure compensation + // settings will still affect the exposure settings while + // auto-exposure is locked. Stopping preview or taking a still + // image will release the lock. However, the lock can be + // re-enabled prior to preview being re-started, to keep the + // exposure values from the previous lock. In conjunction with + // exposure compensation, this allows for capturing multi-exposure + // brackets with known relative exposure values. Locking + // auto-exposure after open but before the first call to + // startPreview may result in severely over- or under-exposed + // images. The driver may independently enable the AE lock after + // auto-focus completes. If it does so, this key must have its + // value updated to reflect the lock's existence. Applications are + // free to release such a lock, to re-enable AE without restarting + // preview. static const char KEY_AUTO_EXPOSURE_LOCK[]; // Whether locking the auto-exposure is supported. "true" means it is, and // "false" or this key not existing means it is not supported. static const char KEY_AUTO_EXPOSURE_LOCK_SUPPORTED[]; + // The state of the auto-white balance lock. "true" means that + // auto-white balance is locked to its current value and will not + // change. "false" means the auto-white balance routine is free to + // change white balance values. If auto-white balance is already + // locked, setting this to true again has no effect (the driver + // will not recalculate white balance values). Stopping preview or + // taking a still image will release the lock. However, the lock + // can be re-enabled prior to preview being re-started, to keep + // the white balance values from the previous lock. In conjunction + // with exposure compensation, this allows for capturing + // multi-exposure brackets with fixed white balance. Locking + // auto-white balance after open but before the first call to + // startPreview may result in severely incorrect color. The + // driver may independently enable the AWB lock after auto-focus + // completes. If it does so, this key must have its value updated + // to reflect the lock's existence. Applications are free to + // release such a lock, to re-enable AWB without restarting + // preview. + static const char KEY_AUTO_WHITEBALANCE_LOCK[]; + // Whether locking the auto-white balance is supported. "true" + // means it is, and "false" or this key not existing means it is + // not supported. + static const char KEY_AUTO_WHITEBALANCE_LOCK_SUPPORTED[]; + // The maximum number of metering areas supported. This is the maximum // length of KEY_METERING_AREAS. // Example value: "0" or "2". Read only. diff --git a/libs/camera/CameraParameters.cpp b/libs/camera/CameraParameters.cpp index 4f3da404a57d7..c295315138f56 100644 --- a/libs/camera/CameraParameters.cpp +++ b/libs/camera/CameraParameters.cpp @@ -70,6 +70,8 @@ const char CameraParameters::KEY_MIN_EXPOSURE_COMPENSATION[] = "min-exposure-com const char CameraParameters::KEY_EXPOSURE_COMPENSATION_STEP[] = "exposure-compensation-step"; const char CameraParameters::KEY_AUTO_EXPOSURE_LOCK[] = "auto-exposure-lock"; const char CameraParameters::KEY_AUTO_EXPOSURE_LOCK_SUPPORTED[] = "auto-exposure-lock-supported"; +const char CameraParameters::KEY_AUTO_WHITEBALANCE_LOCK[] = "auto-whitebalance-lock"; +const char CameraParameters::KEY_AUTO_WHITEBALANCE_LOCK_SUPPORTED[] = "auto-whitebalance-lock-supported"; const char CameraParameters::KEY_MAX_NUM_METERING_AREAS[] = "max-num-metering-areas"; const char CameraParameters::KEY_METERING_AREAS[] = "metering-areas"; const char CameraParameters::KEY_ZOOM[] = "zoom";