Merge "Improve camera javadoc and fix some errors." into ics-mr0

Author: Wu-cheng Li

core/java/android/hardware/Camera.java

@@ -337,7 +337,7 @@ public final void release() {
      * Camera objects are locked by default unless {@link #unlock()} is
      * called.  Normally {@link #reconnect()} is used instead.
      *
-     * <p>Since API level 13, camera is automatically locked for applications in
+     * <p>Since API level 14, camera is automatically locked for applications in
      * {@link android.media.MediaRecorder#start()}. Applications can use the
      * camera (ex: zoom) after recording starts. There is no need to call this
      * after recording starts or stops.
@@ -356,7 +356,7 @@ public final void release() {
      * which will re-acquire the lock and allow you to continue using the
      * camera.
      *
-     * <p>Since API level 13, camera is automatically locked for applications in
+     * <p>Since API level 14, camera is automatically locked for applications in
      * {@link android.media.MediaRecorder#start()}. Applications can use the
      * camera (ex: zoom) after recording starts. There is no need to call this
      * after recording starts or stops.
@@ -781,7 +781,7 @@ public interface AutoFocusCallback
          * @see android.hardware.Camera.Parameters#setAutoWhiteBalanceLock(boolean)
          */
         void onAutoFocus(boolean success, Camera camera);
-    };
+    }
 
     /**
      * Starts camera auto-focus and registers a callback function to run when
@@ -804,11 +804,17 @@ public interface AutoFocusCallback
      * {@link android.hardware.Camera.Parameters#FLASH_MODE_OFF}, flash may be
      * fired during auto-focus, depending on the driver and camera hardware.<p>
      *
-     * Auto-exposure lock {@link android.hardware.Camera.Parameters#getAutoExposureLock()}
+     * <p>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.
      *
+     * <p>Stopping preview with {@link #stopPreview()}, or triggering still
+     * image capture with {@link #takePicture(Camera.ShutterCallback,
+     * Camera.PictureCallback, Camera.PictureCallback)}, will not change the
+     * the focus position. Applications must call cancelAutoFocus to reset the
+     * focus.</p>
+     *
      * @param cb the callback to run
      * @see #cancelAutoFocus()
      * @see android.hardware.Camera.Parameters#setAutoExposureLock(boolean)
@@ -1059,8 +1065,7 @@ public interface FaceDetectionListener
         /**
          * Notify the listener of the detected faces in the preview frame.
          *
-         * @param faces The detected faces in a list sorted by the confidence score.
-         *              The highest scored face is the first element.
+         * @param faces The detected faces in a list
          * @param camera  The {@link Camera} service object
          */
         void onFaceDetection(Face[] faces, Camera camera);
@@ -1121,7 +1126,7 @@ public final void stopFaceDetection() {
 
     /**
      * Information about a face identified through camera face detection.
-     * 
+     *
      * <p>When face detection is used with a camera, the {@link FaceDetectionListener} returns a
      * list of face objects for use in focusing and metering.</p>
      *
@@ -1140,7 +1145,9 @@ public Face() {
          * the field of view. For example, suppose the size of the viewfinder UI
          * is 800x480. The rect passed from the driver is (-1000, -1000, 0, 0).
          * The corresponding viewfinder rect should be (0, 0, 400, 240). The
-         * width and height of the rect will not be 0 or negative.
+         * width and height of the rect will not be 0 or negative. The
+         * coordinates can be smaller than -1000 or bigger than 1000. But at
+         * least one vertex will be within (-1000, -1000) and (1000, 1000).
          *
          * <p>The direction is relative to the sensor orientation, that is, what
          * the sensor sees. The direction is not affected by the rotation or
@@ -1653,23 +1660,36 @@ public class Parameters {
          * call {@link #takePicture(Camera.ShutterCallback,
          * Camera.PictureCallback, Camera.PictureCallback)} in this mode but the
          * subject may not be in focus. Auto focus starts when the parameter is
-         * set. Applications should not call {@link
-         * #autoFocus(AutoFocusCallback)} in this mode. To stop continuous
-         * focus, applications should change the focus mode to other modes.
+         * set.
+         *
+         * <p>Since API level 14, applications can call {@link
+         * #autoFocus(AutoFocusCallback)} in this mode. The focus callback will
+         * immediately return with a boolean that indicates whether the focus is
+         * sharp or not. The focus position is locked after autoFocus call. If
+         * applications want to resume the continuous focus, cancelAutoFocus
+         * must be called. Restarting the preview will not resume the continuous
+         * autofocus. To stop continuous focus, applications should change the
+         * focus mode to other modes.
+         *
+         * @see #FOCUS_MODE_CONTINUOUS_PICTURE
          */
         public static final String FOCUS_MODE_CONTINUOUS_VIDEO = "continuous-video";
 
         /**
          * Continuous auto focus mode intended for taking pictures. The camera
          * continuously tries to focus. The speed of focus change is more
          * aggressive than {@link #FOCUS_MODE_CONTINUOUS_VIDEO}. Auto focus
-         * starts when the parameter is set. If applications call {@link
-         * #autoFocus(AutoFocusCallback)} in this mode, the focus callback will
-         * immediately return with a boolean that indicates whether the focus is
-         * sharp or not. The apps can then decide if they want to take a picture
-         * immediately or to change the focus mode to auto, and run a full
-         * autofocus cycle. To stop continuous focus, applications should change
-         * the focus mode to other modes.
+         * starts when the parameter is set.
+         *
+         * <p>If applications call {@link #autoFocus(AutoFocusCallback)} in this
+         * mode, the focus callback will immediately return with a boolean that
+         * indicates whether the focus is sharp or not. The apps can then decide
+         * if they want to take a picture immediately or to change the focus
+         * mode to auto, and run a full autofocus cycle. The focus position is
+         * locked after autoFocus call. If applications want to resume the
+         * continuous focus, cancelAutoFocus must be called. Restarting the
+         * preview will not resume the continuous autofocus. To stop continuous
+         * focus, applications should change the focus mode to other modes.
          *
          * @see #FOCUS_MODE_CONTINUOUS_VIDEO
          */
@@ -3061,8 +3081,9 @@ public int getMaxNumFocusAreas() {
          * when using zoom.</p>
          *
          * <p>Focus area only has effect if the current focus mode is
-         * {@link #FOCUS_MODE_AUTO}, {@link #FOCUS_MODE_MACRO}, or
-         * {@link #FOCUS_MODE_CONTINUOUS_VIDEO}.</p>
+         * {@link #FOCUS_MODE_AUTO}, {@link #FOCUS_MODE_MACRO},
+         * {@link #FOCUS_MODE_CONTINUOUS_VIDEO}, or
+         * {@link #FOCUS_MODE_CONTINUOUS_PICTURE}.</p>
          *
          * @return a list of current focus areas
          */

include/camera/CameraParameters.h

@@ -283,7 +283,8 @@ class CameraParameters
     // outside the current field of view, even when using zoom.
     //
     // Focus area only has effect if the current focus mode is FOCUS_MODE_AUTO,
-    // FOCUS_MODE_MACRO, or FOCUS_MODE_CONTINOUS_VIDEO.
+    // FOCUS_MODE_MACRO, FOCUS_MODE_CONTINUOUS_VIDEO, or
+    // FOCUS_MODE_CONTINUOUS_PICTURE.
     // Example value: "(-10,-10,0,0,300),(0,0,10,10,700)". Read/write.
     static const char KEY_FOCUS_AREAS[];
     // Focal length in millimeter.
@@ -629,19 +630,29 @@ class CameraParameters
     // recording because the focus changes smoothly . Applications still can
     // call CameraHardwareInterface.takePicture in this mode but the subject may
     // not be in focus. Auto focus starts when the parameter is set.
-    // Applications should not call CameraHardwareInterface.autoFocus in this
-    // mode. To stop continuous focus, applications should change the focus mode
-    // to other modes.
+    //
+    // Applications can call CameraHardwareInterface.autoFocus in this mode. The
+    // focus callback will immediately return with a boolean that indicates
+    // whether the focus is sharp or not. The focus position is locked after
+    // autoFocus call. If applications want to resume the continuous focus,
+    // cancelAutoFocus must be called. Restarting the preview will not resume
+    // the continuous autofocus. To stop continuous focus, applications should
+    // change the focus mode to other modes.
     static const char FOCUS_MODE_CONTINUOUS_VIDEO[];
     // Continuous auto focus mode intended for taking pictures. The camera
     // continuously tries to focus. The speed of focus change is more aggressive
     // than FOCUS_MODE_CONTINUOUS_VIDEO. Auto focus starts when the parameter is
-    // set. If applications call autoFocus in this mode, the focus callback will
-    // immediately return with a boolean that indicates the focus is sharp or
-    // not. The apps can then decide if they want to take a picture immediately
-    // or to change the focus mode to auto, and run a full autofocus cycle. To
-    // stop continuous focus, applications should change the focus mode to other
-    // modes.
+    // set.
+    //
+    // If applications call CameraHardwareInterface.autoFocus in this mode, the
+    // focus callback will immediately return with a boolean that indicates
+    // whether the focus is sharp or not. The apps can then decide if they want
+    // to take a picture immediately or to change the focus mode to auto, and
+    // run a full autofocus cycle. The focus position is locked after autoFocus
+    // call. If applications want to resume the continuous focus,
+    // cancelAutoFocus must be called. Restarting the preview will not resume
+    // the continuous autofocus. To stop continuous focus, applications should
+    // change the focus mode to other modes.
     static const char FOCUS_MODE_CONTINUOUS_PICTURE[];
 
 private: