docs only.
add documentation to notify developers about variable
camera specifications and add some more links
Change-Id: I46ef9811af17858cbc6547f88e626becb481b043
diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index 091bc17..142bbd9 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -35,6 +35,23 @@
* frames for encoding for video.
* <p>There is no default constructor for this class. Use {@link #open()} to
* get a Camera object.</p>
+ *
+ * <p>In order to use the device camera, you must declare the
+ * {@link android.Manifest.permission#CAMERA} permission in your Android
+ * Manifest. Also be sure to include the
+ * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a>
+ * manifest element in order to declare camera features used by your application.
+ * For example, if you use the camera and auto-focus feature, your Manifest
+ * should include the following:</p>
+ * <pre> <uses-permission android:name="android.permission.CAMERA" />
+ * <uses-feature android:name="android.hardware.camera" />
+ * <uses-feature android:name="android.hardware.camera.autofocus" /></pre>
+ *
+ * <p class="caution"><strong>Caution:</strong> Different Android-powered devices
+ * may have different hardware specifications, such as megapixel ratings and
+ * auto-focus capabilities. In order for your application to be compatible with
+ * more devices, you should not make assumptions about the device camera
+ * specifications.</p>
*/
public class Camera {
private static final String TAG = "Camera";
@@ -172,8 +189,9 @@
/**
* The callback that delivers the preview frames.
*
- * @param data The contents of the preview frame in getPreviewFormat()
- * format.
+ * @param data The contents of the preview frame in the format defined
+ * by {@link android.graphics.PixelFormat}, which can be queried
+ * with {@link android.hardware.Camera.Parameters#getPreviewFormat()}.
* @param camera The Camera service object.
*/
void onPreviewFrame(byte[] data, Camera camera);
@@ -296,6 +314,13 @@
/**
* Handles the callback for the camera auto focus.
+ * <p>Devices that do not support auto-focus will receive a "fake"
+ * callback to this interface. If your application needs auto-focus and
+ * should not be installed on devices <em>without</em> auto-focus, you must
+ * declare that your app uses the
+ * {@code android.hardware.camera.autofocus} feature, in the
+ * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a>
+ * manifest element.</p>
*/
public interface AutoFocusCallback
{
@@ -312,6 +337,14 @@
* Starts auto-focus function and registers a callback function to
* run when camera is focused. Only valid after startPreview() has
* been called.
+ * <p>Devices that do not support auto-focus will trigger a "fake"
+ * callback to the
+ * {@link android.hardware.Camera.AutoFocusCallback}.
+ * If your application should not be installed
+ * on devices without auto-focus, you must declare that your application
+ * uses auto-focus with the
+ * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a>
+ * manifest element.</p>
*
* @param cb the callback to run
*/
@@ -668,10 +701,15 @@
}
/**
- * Sets the image format for preview pictures.
+ * Sets the image format for preview pictures.
+ * <p>If the image format is not set with this method, then the
+ * preview format will default to
+ * {@link android.graphics.PixelFormat#YCbCr_420_SP}, which
+ * uses the NV21 encoding format.</p>
*
- * @param pixel_format the desired preview picture format
- * (<var>PixelFormat.YCbCr_420_SP</var>,
+ * @param pixel_format the desired preview picture format, defined
+ * by one of the {@link android.graphics.PixelFormat} constants.
+ * (E.g., <var>PixelFormat.YCbCr_420_SP</var> (default),
* <var>PixelFormat.RGB_565</var>, or
* <var>PixelFormat.JPEG</var>)
* @see android.graphics.PixelFormat
@@ -688,7 +726,8 @@
/**
* Returns the image format for preview pictures.
*
- * @return the PixelFormat int representing the preview picture format
+ * @return the {@link android.graphics.PixelFormat} int representing
+ * the preview picture format.
*/
public int getPreviewFormat() {
return pixelFormatForCameraFormat(get("preview-format"));
diff --git a/graphics/java/android/graphics/PixelFormat.java b/graphics/java/android/graphics/PixelFormat.java
index 159accc..221c2f8 100644
--- a/graphics/java/android/graphics/PixelFormat.java
+++ b/graphics/java/android/graphics/PixelFormat.java
@@ -52,6 +52,12 @@
* by the hardware.
*/
public static final int YCbCr_422_SP= 0x10;
+
+ /** YCbCr format used for images, which uses the NV21 encoding format.
+ * This is the default format for camera preview images, when not
+ * otherwise set with
+ * {@link android.hardware.Camera.Parameters#setPreviewFormat(int)}.
+ */
public static final int YCbCr_420_SP= 0x11;
/**
