am 589e8381: Merge "Improve camera documentation." into gingerbread

* commit '589e838116b0dffa696fa39336d0588124877f98':
  Improve camera documentation.

core/java/android/hardware/Camera.java

@@ -906,6 +906,7 @@ public class Camera {
      * Changes the settings for this Camera service.
      *
      * @param params the Parameters to use for this Camera service
+     * @throws RuntimeException if any parameter is invalid or not supported.
      * @see #getParameters()
      */
     public void setParameters(Parameters params) {

include/camera/Camera.h

@@ -105,8 +105,8 @@ enum {
 };
 
 enum {
-    CAMERA_FACING_BACK = 0,
+    CAMERA_FACING_BACK = 0, /* The facing of the camera is opposite to that of the screen. */
-    CAMERA_FACING_FRONT = 1 /* The camera faces to the user */
+    CAMERA_FACING_FRONT = 1 /* The facing of the camera is the same as that of the screen. */
 };
 
 struct CameraInfo {
@@ -122,10 +122,12 @@ struct CameraInfo {
      * camera image needs to be rotated clockwise so it shows correctly on
      * the display in its natural orientation. It should be 0, 90, 180, or 270.
      *
-     * For example, suppose a device has a naturally tall screen, but the camera
+     * For example, suppose a device has a naturally tall screen. The
-     * sensor is mounted in landscape. If the top side of the camera sensor is
+     * back-facing camera sensor is mounted in landscape. You are looking at
-     * aligned with the right edge of the display in natural orientation, the
+     * the screen. If the top side of the camera sensor is aligned with the
-     * value should be 90.
+     * right edge of the screen in natural orientation, the value should be
+     * 90. If the top side of a front-facing camera sensor is aligned with
+     * the right of the screen, the value should be 270.
      */
     int orientation;
 };

include/camera/CameraHardwareInterface.h

@@ -190,7 +190,9 @@ public:
      */
     virtual status_t    cancelPicture() = 0;
 
-    /** Set the camera parameters. */
+    /**
+     * Set the camera parameters. This returns BAD_VALUE if any parameter is
+     * invalid or not supported. */
     virtual status_t    setParameters(const CameraParameters& params) = 0;
 
     /** Return the camera parameters. */

include/camera/CameraParameters.h

@@ -142,16 +142,23 @@ public:
     // the best.
     // Example value: "90". Read/write.
     static const char KEY_JPEG_QUALITY[];
-    // The orientation of the device in degrees. For example, suppose the
+    // The rotation angle in degrees relative to the orientation of the camera.
-    // natural position of the device is landscape. If the user takes a picture
+    // This affects the pictures returned from CAMERA_MSG_COMPRESSED_IMAGE. The
-    // in landscape mode in 2048x1536 resolution, the rotation will be set to
+    // camera driver may set orientation in the EXIF header without rotating the
-    // "0". If the user rotates the phone 90 degrees clockwise, the rotation
+    // picture. Or the driver may rotate the picture and the EXIF thumbnail. If
-    // should be set to "90".
+    // the Jpeg picture is rotated, the orientation in the EXIF header will be
-    // The camera driver can set orientation in the EXIF header without rotating
+    // missing or 1 (row #0 is top and column #0 is left side).
-    // the picture. Or the driver can rotate the picture and the EXIF thumbnail.
+    //
-    // If the Jpeg picture is rotated, the orientation in the EXIF header should
+    // Note that the JPEG pictures of front-facing cameras are not mirrored
-    // be missing or 1 (row #0 is top and column #0 is left side). The driver
+    // as in preview display.
-    // should not set default value for this parameter.
+    //
+    // For example, suppose the natural orientation of the device is portrait.
+    // The device is rotated 270 degrees clockwise, so the device orientation is
+    // 270. Suppose a back-facing camera sensor is mounted in landscape and the
+    // top side of the camera sensor is aligned with the right edge of the
+    // display in natural orientation. So the camera orientation is 90. The
+    // rotation should be set to 0 (270 + 90).
+    //
     // Example value: "0" or "90" or "180" or "270". Write only.
     static const char KEY_ROTATION[];
     // GPS latitude coordinate. GPSLatitude and GPSLatitudeRef will be stored in