Merge "Improve camera face detection javadoc." into ics-mr1
diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 3becec0..c2a757f 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -1111,9 +1111,21 @@
* 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 @@
* 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
- * 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).
+ * The corresponding viewfinder rect should be (0, 0, 400, 240). It is
+ * guaranteed left < right and top < bottom. 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
- * 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()
*/