From c157e0cd161e5b3b28b72bafebb3360ed856a608 Mon Sep 17 00:00:00 2001
From: Wu-cheng Li <wuchengli@google.com>
Date: Thu, 7 Oct 2010 18:36:07 +0800
Subject: Add javadoc for display orientation.

Display orientation should be considered while setting preview size,
picture size, or thumbnail size.

bug:3051937
Change-Id: I3b6bd1b920e4752ffdfc8aec56a0da9d474dd630
---
 core/java/android/hardware/Camera.java | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

(limited to 'core/java/android/hardware')

diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 7b930d5..a27ba84 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -1354,8 +1354,23 @@ public class Camera {
         /**
          * Sets the dimensions for preview pictures.
          *
+         * The sides of width and height are based on camera orientation. That
+         * is, the preview size is the size before it is rotated by display
+         * orientation. So applications need to consider the display orientation
+         * while setting preview size. For example, suppose the camera supports
+         * both 480x320 and 320x480 preview sizes. The application wants a 3:2
+         * preview ratio. If the display orientation is set to 0 or 180, preview
+         * size should be set to 480x320. If the display orientation is set to
+         * 90 or 270, preview size should be set to 320x480. The display
+         * orientation should also be considered while setting picture size and
+         * thumbnail size.
+         *
          * @param width  the width of the pictures, in pixels
          * @param height the height of the pictures, in pixels
+         * @see #setDisplayOrientation(int)
+         * @see #getCameraInfo(int, CameraInfo)
+         * @see #setPictureSize(int, int)
+         * @see #setJpegThumbnailSize(int, int)
          */
         public void setPreviewSize(int width, int height) {
             String v = Integer.toString(width) + "x" + Integer.toString(height);
@@ -1389,8 +1404,12 @@ public class Camera {
          * applications set both width and height to 0, EXIF will not contain
          * thumbnail.
          *
+         * Applications need to consider the display orientation. See {@link
+         * #setPreviewSize(int,int)} for reference.
+         *
          * @param width  the width of the thumbnail, in pixels
          * @param height the height of the thumbnail, in pixels
+         * @see #setPreviewSize(int,int)
          */
         public void setJpegThumbnailSize(int width, int height) {
             set(KEY_JPEG_THUMBNAIL_WIDTH, width);
@@ -1606,8 +1625,13 @@ public class Camera {
         /**
          * Sets the dimensions for pictures.
          *
+         * Applications need to consider the display orientation. See {@link
+         * #setPreviewSize(int,int)} for reference.
+         *
          * @param width  the width for pictures, in pixels
          * @param height the height for pictures, in pixels
+         * @see #setPreviewSize(int,int)
+         *
          */
         public void setPictureSize(int width, int height) {
             String v = Integer.toString(width) + "x" + Integer.toString(height);
-- 
cgit v1.1