am b90a70d1: Merge "Improve camera face detection javadoc." into ics-mr1

* commit 'b90a70d1542edd5a95e73b75192e6eb5a66401cc':
  Improve camera face detection javadoc.

core/java/android/hardware/Camera.java

@@ -1111,9 +1111,21 @@ public class Camera {
      * Parameters#getMaxNumDetectedFaces()} returns a number larger than 0.
      * If the face detection has started, apps should not call this again.
      *
-     * When the face detection is running, {@link Parameters#setWhiteBalance(String)},
+     * <p>When the face detection is running, {@link Parameters#setWhiteBalance(String)},
      * {@link Parameters#setFocusAreas(List)}, and {@link Parameters#setMeteringAreas(List)}
-     * have no effect.
+     * have no effect. The camera uses the detected faces to do auto-white balance,
+     * auto exposure, and autofocus.
+     *
+     * <p>If the apps call {@link #autoFocus(AutoFocusCallback)}, the camera
+     * will stop sending face callbacks. The last face callback indicates the
+     * areas used to do autofocus. After focus completes, face detection will
+     * resume sending face callbacks. If the apps call {@link
+     * #cancelAutoFocus()}, the face callbacks will also resume.</p>
+     *
+     * <p>After calling {@link #takePicture(Camera.ShutterCallback, Camera.PictureCallback,
+     * Camera.PictureCallback)} or {@link #stopPreview()}, and then resuming
+     * preview with {@link #startPreview()}, the apps should call this method
+     * again to resume face detection.</p>
      *
      * @throws IllegalArgumentException if the face detection is unsupported.
      * @throws RuntimeException if the method fails or the face detection is
@@ -1163,14 +1175,31 @@ public class Camera {
          * camera field of view, and (1000, 1000) represents the bottom-right of
          * 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
+         * The corresponding viewfinder rect should be (0, 0, 400, 240). It is
-         * width and height of the rect will not be 0 or negative. The
+         * guaranteed left < right and top < bottom. The coordinates can be
-         * coordinates can be smaller than -1000 or bigger than 1000. But at
+         * smaller than -1000 or bigger than 1000. But at least one vertex will
-         * least one vertex will be within (-1000, -1000) and (1000, 1000).
+         * 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
-         * mirroring of {@link #setDisplayOrientation(int)}.</p>
+         * mirroring of {@link #setDisplayOrientation(int)}. The face bounding
+         * rectangle does not provide any information about face orientation.</p>
+         *
+         * <p>Here is the matrix to convert driver coordinates to View coordinates
+         * in pixels.</p>
+         * <pre>
+         * Matrix matrix = new Matrix();
+         * CameraInfo info = CameraHolder.instance().getCameraInfo()[cameraId];
+         * // Need mirror for front camera.
+         * boolean mirror = (info.facing == CameraInfo.CAMERA_FACING_FRONT);
+         * matrix.setScale(mirror ? -1 : 1, 1);
+         * // This is the value for android.hardware.Camera.setDisplayOrientation.
+         * matrix.postRotate(displayOrientation);
+         * // Camera driver coordinates range from (-1000, -1000) to (1000, 1000).
+         * // UI coordinates range from (0, 0) to (width, height).
+         * matrix.postScale(view.getWidth() / 2000f, view.getHeight() / 2000f);
+         * matrix.postTranslate(view.getWidth() / 2f, view.getHeight() / 2f);
+         * </pre>
          *
          * @see #startFaceDetection()
          */