Improve camera documentation.
bug:3212606
Change-Id: Iee7106e4665c08a4c75471114010b75d63ac74ce
diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 378189e..f3b2c81 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -906,6 +906,7 @@
* 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) {
diff --git a/include/camera/Camera.h b/include/camera/Camera.h
index e6d84ba..e734c38 100644
--- a/include/camera/Camera.h
+++ b/include/camera/Camera.h
@@ -105,8 +105,8 @@
};
enum {
- CAMERA_FACING_BACK = 0,
- CAMERA_FACING_FRONT = 1 /* The camera faces to the user */
+ CAMERA_FACING_BACK = 0, /* The facing of the camera is opposite to that of the screen. */
+ CAMERA_FACING_FRONT = 1 /* The facing of the camera is the same as that of the screen. */
};
struct CameraInfo {
@@ -122,10 +122,12 @@
* 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
- * sensor is mounted in landscape. If the top side of the camera sensor is
- * aligned with the right edge of the display in natural orientation, the
- * value should be 90.
+ * For example, suppose a device has a naturally tall screen. The
+ * back-facing camera sensor is mounted in landscape. You are looking at
+ * the screen. If the top side of the camera sensor is aligned with the
+ * 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;
};
diff --git a/include/camera/CameraHardwareInterface.h b/include/camera/CameraHardwareInterface.h
index 6a66e3c..35c5aa1 100644
--- a/include/camera/CameraHardwareInterface.h
+++ b/include/camera/CameraHardwareInterface.h
@@ -190,7 +190,9 @@
*/
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. */
diff --git a/include/camera/CameraParameters.h b/include/camera/CameraParameters.h
index 53039a0..4e770fd 100644
--- a/include/camera/CameraParameters.h
+++ b/include/camera/CameraParameters.h
@@ -142,16 +142,23 @@
// the best.
// Example value: "90". Read/write.
static const char KEY_JPEG_QUALITY[];
- // The orientation of the device in degrees. For example, suppose the
- // natural position of the device is landscape. If the user takes a picture
- // in landscape mode in 2048x1536 resolution, the rotation will be set to
- // "0". If the user rotates the phone 90 degrees clockwise, the rotation
- // should be set to "90".
- // The camera driver can set orientation in the EXIF header without rotating
- // 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
- // be missing or 1 (row #0 is top and column #0 is left side). The driver
- // should not set default value for this parameter.
+ // The rotation angle in degrees relative to the orientation of the camera.
+ // This affects the pictures returned from CAMERA_MSG_COMPRESSED_IMAGE. The
+ // camera driver may set orientation in the EXIF header without rotating the
+ // picture. Or the driver may rotate the picture and the EXIF thumbnail. If
+ // the Jpeg picture is rotated, the orientation in the EXIF header will be
+ // missing or 1 (row #0 is top and column #0 is left side).
+ //
+ // Note that the JPEG pictures of front-facing cameras are not mirrored
+ // as in preview display.
+ //
+ // 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
