Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 3d9a9e55 authored by Wei Huang's avatar Wei Huang Committed by Android (Google) Code Review
Browse files

Merge "Update camera javadoc about AE and AWB lock." into ics-factoryrom

parents c4517842 b4f95be0

core/java/android/hardware/Camera.java

+23 −68
Original line number Diff line number Diff line
@@ -772,15 +772,8 @@ 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.

         * The auto-focus routine does not lock auto-exposure and auto-white

         * balance after it completes.

         *

         * @param success true if focus was successful, false if otherwise

         * @param camera  the Camera service object
@@ -811,16 +804,10 @@ 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.

     * Auto-exposure lock {@link android.hardware.Camera.Parameters#getAutoExposureLock()}

     * and auto-white balance locks {@link android.hardware.Camera.Parameters#getAutoWhiteBalanceLock()}

     * do not change during and after autofocus. But auto-focus routine may stop

     * auto-exposure and auto-white balance transiently during focusing.

     *

     * @param cb the callback to run

     * @see #cancelAutoFocus()
@@ -840,13 +827,7 @@ 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()

    {
@@ -2784,13 +2765,12 @@ public class Camera { 
         *

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

         * Camera.PictureCallback, Camera.PictureCallback)}, will not change the

         * lock.</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>Exposure compensation, auto-exposure lock, and auto-white balance

         * lock 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
@@ -2799,14 +2779,6 @@ public class Camera { 
         * run at all, and may result in severely over- or under-exposed

         * 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

         *        auto-exposure is locked, false means that the auto-exposure

         *        routine is free to run normally.
@@ -2823,11 +2795,7 @@ public class Camera { 
         * {@link #setAutoExposureLock} for details about the lock.

         *

         * @return State of the auto-exposure lock. Returns true if

         *         auto-exposure is currently locked, and false otherwise. The

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

         *         auto-exposure is currently locked, and false otherwise.

         *

         * @see #setAutoExposureLock(boolean)

         *
@@ -2865,29 +2833,20 @@ public class Camera { 
         *

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

         * Camera.PictureCallback, Camera.PictureCallback)}, will not change the

         * the lock.</p>

         *

         * <p> Changing the white balance mode with {@link #setWhiteBalance}

         * will release the auto-white balance lock if it is set.</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>

         * <p>Exposure compensation, AE lock, and AWB lock 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>

         *

         * @param toggle new state of the auto-white balance lock. True means

         *        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

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

         *         otherwise.

         *

         * @see #setAutoWhiteBalanceLock(boolean)

         *

include/camera/CameraParameters.h

+6 −16
Original line number Diff line number Diff line
@@ -317,18 +317,13 @@ public: 
    // 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

    // image will not change the 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.

    // images.  The driver will not change the AE lock after

    // auto-focus completes.

    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.
@@ -339,18 +334,13 @@ public: 
    // 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

    // taking a still image will not change the 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.

    // driver will not change the AWB lock after auto-focus

    // completes.

    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