Merge "Update camera javadoc about AE and AWB lock." into ics-factoryrom (3d9a9e55) · Commits · e / os / android_frameworks_base

core/java/android/hardware/Camera.java

+23 −68

Original line number	Original line	Diff line number	Diff line
	@@ -772,15 +772,8 @@ public class Camera {
	* onAutoFocus will be called immediately with a fake value of		* onAutoFocus will be called immediately with a fake value of
	* <code>success</code> set to <code>true</code>.		* <code>success</code> set to <code>true</code>.
	*		*
	* The auto-focus routine may lock auto-exposure and auto-white balance		* The auto-focus routine does not lock auto-exposure and auto-white
	* after it completes. To check for the state of these locks, use the		* balance after it completes.
	* {@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 success true if focus was successful, false if otherwise
	* @param camera the Camera service object		* @param camera the Camera service object
	@@ -811,16 +804,10 @@ public class Camera {
	* {@link android.hardware.Camera.Parameters#FLASH_MODE_OFF}, flash may be		* {@link android.hardware.Camera.Parameters#FLASH_MODE_OFF}, flash may be
	* fired during auto-focus, depending on the driver and camera hardware.<p>		* fired during auto-focus, depending on the driver and camera hardware.<p>
	*		*
	* The auto-focus routine may lock auto-exposure and auto-white balance		* Auto-exposure lock {@link android.hardware.Camera.Parameters#getAutoExposureLock()}
	* after it completes. To check for the state of these locks, use the		* and auto-white balance locks {@link android.hardware.Camera.Parameters#getAutoWhiteBalanceLock()}
	* {@link android.hardware.Camera.Parameters#getAutoExposureLock()} and		* do not change during and after autofocus. But auto-focus routine may stop
	* {@link android.hardware.Camera.Parameters#getAutoWhiteBalanceLock()}		* auto-exposure and auto-white balance transiently during focusing.
	* 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		* @param cb the callback to run
	* @see #cancelAutoFocus()		* @see #cancelAutoFocus()
	@@ -840,13 +827,7 @@ public class Camera {
	* this function will return the focus position to the default.		* this function will return the focus position to the default.
	* If the camera does not support auto-focus, this is a no-op.		* 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 #autoFocus(Camera.AutoFocusCallback)
	* @see android.hardware.Camera.Parameters#setAutoExposureLock(boolean)
	* @see android.hardware.Camera.Parameters#setAutoWhiteBalanceLock(boolean)
	*/		*/
	public final void cancelAutoFocus()		public final void cancelAutoFocus()
	{		{
	@@ -2784,13 +2765,12 @@ public class Camera {
	*		*
	* <p>Stopping preview with {@link #stopPreview()}, or triggering still		* <p>Stopping preview with {@link #stopPreview()}, or triggering still
	* image capture with {@link #takePicture(Camera.ShutterCallback,		* image capture with {@link #takePicture(Camera.ShutterCallback,
	* Camera.PictureCallback, Camera.PictureCallback)}, will automatically		* Camera.PictureCallback, Camera.PictureCallback)}, will not change the
	* set the lock to false. However, the lock can be re-enabled before		* lock.</p>
	* preview is re-started to keep the same AE parameters.</p>
	*		*
	* <p>Exposure compensation, in conjunction with re-enabling the AE and		* <p>Exposure compensation, auto-exposure lock, and auto-white balance
	* AWB locks after each still capture, can be used to capture an		* lock can be used to capture an exposure-bracketed burst of images,
	* exposure-bracketed burst of images, for example.</p>		* for example.</p>
	*		*
	* <p>Auto-exposure state, including the lock state, will not be		* <p>Auto-exposure state, including the lock state, will not be
	* maintained after camera {@link #release()} is called. Locking		* maintained after camera {@link #release()} is called. Locking
	@@ -2799,14 +2779,6 @@ public class Camera {
	* run at all, and may result in severely over- or under-exposed		* run at all, and may result in severely over- or under-exposed
	* images.</p>		* images.</p>
	*		*
	* <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.</p>
	*
	* @param toggle new state of the auto-exposure lock. True means that		* @param toggle new state of the auto-exposure lock. True means that
	* auto-exposure is locked, false means that the auto-exposure		* auto-exposure is locked, false means that the auto-exposure
	* routine is free to run normally.		* routine is free to run normally.
	@@ -2823,11 +2795,7 @@ public class Camera {
	* {@link #setAutoExposureLock} for details about the lock.		* {@link #setAutoExposureLock} for details about the lock.
	*		*
	* @return State of the auto-exposure lock. Returns true if		* @return State of the auto-exposure lock. Returns true if
	* auto-exposure is currently locked, and false otherwise. The		* auto-exposure is currently locked, and false otherwise.
	* auto-exposure 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 AE.
	*		*
	* @see #setAutoExposureLock(boolean)		* @see #setAutoExposureLock(boolean)
	*		*
	@@ -2865,29 +2833,20 @@ public class Camera {
	*		*
	* <p>Stopping preview with {@link #stopPreview()}, or triggering still		* <p>Stopping preview with {@link #stopPreview()}, or triggering still
	* image capture with {@link #takePicture(Camera.ShutterCallback,		* image capture with {@link #takePicture(Camera.ShutterCallback,
	* Camera.PictureCallback, Camera.PictureCallback)}, will automatically		* Camera.PictureCallback, Camera.PictureCallback)}, will not change the
	* set the lock to false. However, the lock can be re-enabled before		* the lock.</p>
	* preview is re-started to keep the same white balance parameters.</p>
	*		*
	* <p> Changing the white balance mode with {@link #setWhiteBalance}		* <p> Changing the white balance mode with {@link #setWhiteBalance}
	* will release the auto-white balance lock if it is set.</p>		* will release the auto-white balance lock if it is set.</p>
	*		*
	* <p>Exposure compensation, in conjunction with re-enabling the AE and		* <p>Exposure compensation, AE lock, and AWB lock can be used to
	* AWB locks after each still capture, can be used to capture an		* capture an exposure-bracketed burst of images, for example.
	* exposure-bracketed burst of images, for example. Auto-white balance		* Auto-white balance state, including the lock state, will not be
	* state, including the lock state, will not be maintained after camera		* maintained after camera {@link #release()} is called. Locking
	* {@link #release()} is called. Locking auto-white balance after		* auto-white balance after {@link #open()} but before the first call to
	* {@link #open()} but before the first call to {@link #startPreview()}		* {@link #startPreview()} will not allow the auto-white balance routine
	* will not allow the auto-white balance routine to run at all, and may		* to run at all, and may result in severely incorrect color in captured
	* result in severely incorrect color in captured images.</p>		* 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		* @param toggle new state of the auto-white balance lock. True means
	* that auto-white balance is locked, false means that the		* that auto-white balance is locked, false means that the
	@@ -2908,11 +2867,7 @@ public class Camera {
	*		*
	* @return State of the auto-white balance lock. Returns true if		* @return State of the auto-white balance lock. Returns true if
	* auto-white balance is currently locked, and false		* auto-white balance is currently locked, and false
	* otherwise. The auto-white balance lock may be independently		* otherwise.
	* 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)		* @see #setAutoWhiteBalanceLock(boolean)
	*		*

include/camera/CameraParameters.h

+6 −16

Original line number	Original line	Diff line number	Diff line
	@@ -317,18 +317,13 @@ public:
	// recalculate exposure values). Changing exposure compensation		// recalculate exposure values). Changing exposure compensation
	// settings will still affect the exposure settings while		// settings will still affect the exposure settings while
	// auto-exposure is locked. Stopping preview or taking a still		// auto-exposure is locked. Stopping preview or taking a still
	// image will release the lock. However, the lock can be		// image will not change the lock. In conjunction with
	// 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		// exposure compensation, this allows for capturing multi-exposure
	// brackets with known relative exposure values. Locking		// brackets with known relative exposure values. Locking
	// auto-exposure after open but before the first call to		// auto-exposure after open but before the first call to
	// startPreview may result in severely over- or under-exposed		// startPreview may result in severely over- or under-exposed
	// images. The driver may independently enable the AE lock after		// images. The driver will not change the AE lock after
	// auto-focus completes. If it does so, this key must have its		// auto-focus completes.
	// 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[];		static const char KEY_AUTO_EXPOSURE_LOCK[];
	// Whether locking the auto-exposure is supported. "true" means it is, and		// Whether locking the auto-exposure is supported. "true" means it is, and
	// "false" or this key not existing means it is not supported.		// "false" or this key not existing means it is not supported.
	@@ -339,18 +334,13 @@ public:
	// change white balance values. If auto-white balance is already		// change white balance values. If auto-white balance is already
	// locked, setting this to true again has no effect (the driver		// locked, setting this to true again has no effect (the driver
	// will not recalculate white balance values). Stopping preview or		// will not recalculate white balance values). Stopping preview or
	// taking a still image will release the lock. However, the lock		// taking a still image will not change the lock. In conjunction
	// 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		// with exposure compensation, this allows for capturing
	// multi-exposure brackets with fixed white balance. Locking		// multi-exposure brackets with fixed white balance. Locking
	// auto-white balance after open but before the first call to		// auto-white balance after open but before the first call to
	// startPreview may result in severely incorrect color. The		// startPreview may result in severely incorrect color. The
	// driver may independently enable the AWB lock after auto-focus		// driver will not change the AWB lock after auto-focus
	// completes. If it does so, this key must have its value updated		// completes.
	// 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[];		static const char KEY_AUTO_WHITEBALANCE_LOCK[];
	// Whether locking the auto-white balance is supported. "true"		// Whether locking the auto-white balance is supported. "true"
	// means it is, and "false" or this key not existing means it is		// means it is, and "false" or this key not existing means it is