am ccaa0028: Merge "Improve camera documentation." into gingerbread

Merge commit 'ccaa002848e9ef1ff232eee5babc9273599924af' into gingerbread-plus-aosp

* commit 'ccaa002848e9ef1ff232eee5babc9273599924af':
  Improve camera documentation.

core/java/android/hardware/Camera.java

@@ -1166,6 +1166,14 @@ public class Camera {
          */
         public static final String FOCUS_MODE_EDOF = "edof";
 
+        /**
+         * Continuous auto focus mode. The camera continuously tries to focus.
+         * This is ideal for shooting video or shooting photo of moving object.
+         * Auto focus starts when the parameter is set. Applications should not
+         * call {@link #autoFocus(AutoFocusCallback)} in this mode.
+         */
+        public static final String FOCUS_MODE_CONTINUOUS = "continuous";
+
         // Indices for focus distance array.
         /**
          * The array index of near focus distance for use with
@@ -1185,16 +1193,6 @@ public class Camera {
          */
         public static final int FOCUS_DISTANCE_FAR_INDEX = 2;
 
-        /**
-         * Continuous focus mode. The camera continuously tries to focus. This
-         * is ideal for shooting video or shooting photo of moving object.
-         * Continuous focus starts when {@link #autoFocus(AutoFocusCallback)} is
-         * called. Continuous focus stops when {@link #cancelAutoFocus()} is
-         * called. AutoFocusCallback will be only called once as soon as the
-         * picture is in focus.
-         */
-        public static final String FOCUS_MODE_CONTINUOUS = "continuous";
-
         /**
          * The camera determines the exposure by giving more weight to the
          * central part of the scene.
@@ -1942,15 +1940,15 @@ public class Camera {
         /**
          * Gets the current focus mode setting.
          *
-         * @return current focus mode. If the camera does not support
+         * @return current focus mode. This method will always return a non-null
-         *         auto-focus, this should return {@link #FOCUS_MODE_FIXED}. If
+         *         value. Applications should call {@link
-         *         the focus mode is not FOCUS_MODE_FIXED or {@link
+         *         #autoFocus(AutoFocusCallback)} to start the focus if focus
-         *         #FOCUS_MODE_INFINITY}, applications should call {@link
+         *         mode is FOCUS_MODE_AUTO or FOCUS_MODE_MACRO.
-         *         #autoFocus(AutoFocusCallback)} to start the focus.
          * @see #FOCUS_MODE_AUTO
          * @see #FOCUS_MODE_INFINITY
          * @see #FOCUS_MODE_MACRO
          * @see #FOCUS_MODE_FIXED
+         * @see #FOCUS_MODE_CONTINUOUS
          */
         public String getFocusMode() {
             return get(KEY_FOCUS_MODE);
@@ -2152,8 +2150,14 @@ public class Camera {
          * #autoFocus(AutoFocusCallback)}, {@link #cancelAutoFocus}, or {@link
          * #startPreview()}. Applications can call {@link #getParameters()}
          * and this method anytime to get the latest focus distances. If the
-         * focus mode is FOCUS_MODE_CONTINUOUS and autofocus has started, focus
+         * focus mode is FOCUS_MODE_CONTINUOUS, focus distances may change from
-         * distances may change from time to time.
+         * time to time.
+         *
+         * This method is intended to estimate the distance between the camera
+         * and the subject. After autofocus, the subject distance may be within
+         * near and far focus distance. However, the precision depends on the
+         * camera hardware, autofocus algorithm, the focus area, and the scene.
+         * The error can be large and it should be only used as a reference.
          *
          * Far focus distance >= optimal focus distance >= near focus distance.
          * If the focus distance is infinity, the value will be

include/camera/CameraParameters.h

@@ -171,10 +171,9 @@ public:
     // Supported flash modes.
     // Example value: "auto,on,off". Read only.
     static const char KEY_SUPPORTED_FLASH_MODES[];
-    // Current focus mode. If the camera does not support auto-focus, the value
+    // Current focus mode. This will not be empty. Applications should call
-    // should be FOCUS_MODE_FIXED. If the focus mode is not FOCUS_MODE_FIXED or
+    // CameraHardwareInterface.autoFocus to start the focus if focus mode is
-    // or FOCUS_MODE_INFINITY, applications should call
+    // FOCUS_MODE_AUTO or FOCUS_MODE_MACRO.
-    // CameraHardwareInterface.autoFocus to start the focus.
     // Example value: "auto" or FOCUS_MODE_XXX constants. Read/write.
     static const char KEY_FOCUS_MODE[];
     // Supported focus modes.
@@ -231,11 +230,16 @@ public:
     // be in focus. The object is sharpest at the optimal focus distance. The
     // depth of field is the far focus distance minus near focus distance.
     //
-    // Applications can read this parameter anytime to get the latest focus
+    // Focus distances may change after starting auto focus, canceling auto
-    // distances. If the focus mode is FOCUS_MODE_EDOF, the values may be all
+    // focus, or starting the preview. Applications can read this anytime to get
-    // 0, which means focus distance is not applicable. If the focus mode is
+    // the latest focus distances. If the focus mode is FOCUS_MODE_CONTINUOUS,
-    // FOCUS_MODE_CONTINUOUS and autofocus has started, focus distances may
+    // focus distances may change from time to time.
-    // change from time to time.
+    //
+    // This is intended to estimate the distance between the camera and the
+    // subject. After autofocus, the subject distance may be within near and far
+    // focus distance. However, the precision depends on the camera hardware,
+    // autofocus algorithm, the focus area, and the scene. The error can be
+    // large and it should be only used as a reference.
     //
     // Far focus distance > optimal focus distance > near focus distance. If
     // the far focus distance is infinity, the value should be "Infinity" (case
@@ -348,10 +352,10 @@ public:
     // continuously. Applications should not call
     // CameraHardwareInterface.autoFocus in this mode.
     static const char FOCUS_MODE_EDOF[];
-    // Continuous focus mode. The camera continuously tries to focus. This is
+    // Continuous auto focus mode. The camera continuously tries to focus. This
-    // ideal for shooting video or shooting photo of moving object. Continuous
+    // is ideal for shooting video or shooting photo of moving object. Auto
-    // focus starts when CameraHardwareInterface.autoFocus is called. Focus
+    // focus starts when the parameter is set. Applications should not call
-    // callback will be only called once as soon as the picture is in focus.
+    // CameraHardwareInterface.autoFocus in this mode.
     static const char FOCUS_MODE_CONTINUOUS[];
 
     // The camera determines the exposure by giving more weight to the