diff options
Diffstat (limited to 'core')
| -rw-r--r-- | core/java/android/hardware/Camera.java | 462 |
1 files changed, 315 insertions, 147 deletions
diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java index 1100886..19e578f 100644 --- a/core/java/android/hardware/Camera.java +++ b/core/java/android/hardware/Camera.java @@ -32,23 +32,79 @@ import android.os.Looper; import android.os.Message; /** - * The Camera class is used to connect/disconnect with the camera service, - * set capture settings, start/stop preview, snap a picture, and retrieve - * frames for encoding for video. - * <p>There is no default constructor for this class. Use {@link #open()} to - * get a Camera object.</p> + * The Camera class is used to set image capture settings, start/stop preview, + * snap pictures, and retrieve frames for encoding for video. This class is a + * client for the Camera service, which manages the actual camera hardware. * - * <p>In order to use the device camera, you must declare the + * <p>To access 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. + * manifest element 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>To take pictures with this class, use the following steps:</p> + * + * <ol> + * <li>Obtain an instance of Camera from {@link #open(int)}. + * + * <li>Get existing (default) settings with {@link #getParameters()}. + * + * <li>If necessary, modify the returned {@link Camera.Parameters} object and call + * {@link #setParameters(Camera.Parameters)}. + * + * <li>If desired, call {@link #setDisplayOrientation(int)}. + * + * <li><b>Important</b>: Pass a fully initialized {@link SurfaceHolder} to + * {@link #setPreviewDisplay(SurfaceHolder)}. Without a surface, the camera + * will be unable to start the preview. + * + * <li><b>Important</b>: Call {@link #startPreview()} to start updating the + * preview surface. Preview must be started before you can take a picture. + * + * <li>When you want, call {@link #takePicture(Camera.ShutterCallback, + * Camera.PictureCallback, Camera.PictureCallback, Camera.PictureCallback)} to + * capture a photo. Wait for the callbacks to provide the actual image data. + * + * <li>After taking a picture, preview display will have stopped. To take more + * photos, call {@link #startPreview()} again first. + * + * <li>Call {@link #stopPreview()} to stop updating the preview surface. + * + * <li><b>Important:</b> Call {@link #release()} to release the camera for + * use by other applications. Applications should release the camera + * immediately in {@link android.app.Activity#onPause()} (and re-{@link #open()} + * it in {@link android.app.Activity#onResume()}). + * </ol> + * + * <p>To quickly switch to video recording mode, use these steps:</p> + * + * <ol> + * <li>Obtain and initialize a Camera and start preview as described above. + * + * <li>Call {@link #unlock()} to allow the media process to access the camera. + * + * <li>Pass the camera to {@link android.media.MediaRecorder#setCamera(Camera)}. + * See {@link android.media.MediaRecorder} information about video recording. + * + * <li>When finished recording, call {@link #reconnect()} to re-acquire + * and re-lock the camera. + * + * <li>If desired, restart preview and take more photos or videos. + * + * <li>Call {@link #stopPreview()} and {@link #release()} as described above. + * </ol> + * + * <p>This class is not thread-safe, and is meant for use from one event thread. + * Most long-running operations (preview, focus, photo capture, etc) happen + * asynchronously and invoke callbacks as necessary. Callbacks will be invoked + * on the event thread {@link #open(int)} was called from. This class's methods + * must never be called from multiple threads at once.</p> + * * <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 @@ -84,12 +140,12 @@ public class Camera { private boolean mWithBuffer; /** - * Returns the number of Cameras available. + * Returns the number of physical cameras available on this device. */ public native static int getNumberOfCameras(); /** - * Returns the information about the camera. + * Returns the information about a particular camera. * If {@link #getNumberOfCameras()} returns N, the valid id is 0 to N-1. */ public native static void getCameraInfo(int cameraId, CameraInfo cameraInfo); @@ -123,9 +179,30 @@ public class Camera { }; /** - * Returns a new Camera object. - * If {@link #getNumberOfCameras()} returns N, the valid id is 0 to N-1. - * The id 0 is the default camera. + * Creates a new Camera object to access a particular hardware camera. + * + * <p>You must call {@link #release()} when you are done using the camera, + * otherwise it will remain locked and be unavailable to other applications. + * + * <p>Your application should only have one Camera object active at a time + * for a particular hardware camera. + * + * <p>Callbacks from other methods are delivered to the event loop of the + * thread which called open(). If this thread has no event loop, then + * callbacks are delivered to the main application event loop. If there + * is no main application event loop, callbacks are not delivered. + * + * <p class="caution"><b>Caution:</b> On some devices, this method may + * take a long time to complete. It is best to call this method from a + * worker thread (possibly using {@link android.os.AsyncTask}) to avoid + * blocking the main application UI thread. + * + * @param cameraId the hardware camera to access, between 0 and + * {@link #getNumberOfCameras()}-1. Use {@link #CAMERA_ID_DEFAULT} + * to access the default camera. + * @return a new Camera object, connected, locked and ready for use. + * @throws RuntimeException if connection to the camera service fails (for + * example, if the camera is in use by another process). */ public static Camera open(int cameraId) { return new Camera(cameraId); @@ -137,7 +214,8 @@ public class Camera { public static int CAMERA_ID_DEFAULT = 0; /** - * Returns a new Camera object. This returns the default camera. + * Equivalent to Camera.open(Camera.CAMERA_ID_DEFAULT). + * Creates a new Camera object to access the default camera. */ public static Camera open() { return new Camera(CAMERA_ID_DEFAULT); @@ -173,56 +251,83 @@ public class Camera { /** * Disconnects and releases the Camera object resources. - * <p>It is recommended that you call this as soon as you're done with the - * Camera object.</p> + * + * <p>You must call this as soon as you're done with the Camera object.</p> */ public final void release() { native_release(); } /** - * Reconnect to the camera after passing it to MediaRecorder. To save - * setup/teardown time, a client of Camera can pass an initialized Camera - * object to a MediaRecorder to use for video recording. Once the - * MediaRecorder is done with the Camera, this method can be used to - * re-establish a connection with the camera hardware. NOTE: The Camera - * object must first be unlocked by the process that owns it before it - * can be connected to another process. + * Unlocks the camera to allow another process to access it. + * Normally, the camera is locked to the process with an active Camera + * object until {@link #release()} is called. To allow rapid handoff + * between processes, you can call this method to release the camera + * temporarily for another process to use; once the other process is done + * you can call {@link #reconnect()} to reclaim the camera. + * + * <p>This must be done before calling + * {@link android.media.MediaRecorder#setCamera(Camera)}. * - * @throws IOException if the method fails. + * <p>If you are not recording video, you probably do not need this method. + * + * @throws RuntimeException if the camera cannot be unlocked. */ - public native final void reconnect() throws IOException; + public native final void unlock(); /** - * Lock the camera to prevent other processes from accessing it. To save - * setup/teardown time, a client of Camera can pass an initialized Camera - * object to another process. This method is used to re-lock the Camera - * object prevent other processes from accessing it. By default, the - * Camera object is locked. Locking it again from the same process will - * have no effect. Attempting to lock it from another process if it has - * not been unlocked will fail. + * Re-locks the camera to prevent other processes from accessing it. + * Camera objects are locked by default unless {@link #unlock()} is + * called. Normally {@link #reconnect()} is used instead. * - * @throws RuntimeException if the method fails. + * <p>If you are not recording video, you probably do not need this method. + * + * @throws RuntimeException if the camera cannot be re-locked (for + * example, if the camera is still in use by another process). */ public native final void lock(); /** - * Unlock the camera to allow another process to access it. To save - * setup/teardown time, a client of Camera can pass an initialized Camera - * object to another process. This method is used to unlock the Camera - * object before handing off the Camera object to the other process. + * Reconnects to the camera service after another process used it. + * After {@link #unlock()} is called, another process may use the + * camera; when the process is done, you must reconnect to the camera, + * which will re-acquire the lock and allow you to continue using the + * camera. * - * @throws RuntimeException if the method fails. + * <p>This must be done after {@link android.media.MediaRecorder} is + * done recording if {@link android.media.MediaRecorder#setCamera(Camera)} + * was used. + * + * <p>If you are not recording video, you probably do not need this method. + * + * @throws IOException if a connection cannot be re-established (for + * example, if the camera is still in use by another process). */ - public native final void unlock(); + public native final void reconnect() throws IOException; /** - * Sets the SurfaceHolder to be used for a picture preview. If the surface - * changed since the last call, the screen will blank. Nothing happens - * if the same surface is re-set. + * Sets the {@link Surface} to be used for live preview. + * A surface is necessary for preview, and preview is necessary to take + * pictures. The same surface can be re-set without harm. + * + * <p>The {@link SurfaceHolder} must already contain a surface when this + * method is called. If you are using {@link android.view.SurfaceView}, + * you will need to register a {@link SurfaceHolder.Callback} with + * {@link SurfaceHolder#addCallback(SurfaceHolder.Callback)} and wait for + * {@link SurfaceHolder.Callback#surfaceCreated(SurfaceHolder)} before + * calling setPreviewDisplay() or starting preview. + * + * <p>This method must be called before {@link #startPreview()}. The + * one exception is that if the preview surface is not set (or set to null) + * before startPreview() is called, then this method may be called once + * with a non-null parameter to set the preview surface. (This allows + * camera setup and surface creation to happen in parallel, saving time.) + * The preview surface may not otherwise change while preview is running. * - * @param holder the SurfaceHolder upon which to place the picture preview - * @throws IOException if the method fails. + * @param holder containing the Surface on which to place the preview, + * or null to remove the preview surface + * @throws IOException if the method fails (for example, if the surface + * is unavailable or unsuitable). */ public final void setPreviewDisplay(SurfaceHolder holder) throws IOException { if (holder != null) { @@ -235,31 +340,47 @@ public class Camera { private native final void setPreviewDisplay(Surface surface); /** - * Used to get a copy of each preview frame. + * Callback interface used to deliver copies of preview frames as + * they are displayed. + * + * @see #setPreviewCallback(Camera.PreviewCallback) + * @see #setOneShotPreviewCallback(Camera.PreviewCallback) + * @see #setPreviewCallbackWithBuffer(Camera.PreviewCallback) + * @see #startPreview() */ public interface PreviewCallback { /** - * The callback that delivers the preview frames. + * Called as preview frames are displayed. This callback is invoked + * on the event thread {@link #open(int)} was called from. * - * @param data The contents of the preview frame in the format defined + * @param data the contents of the preview frame in the format defined * by {@link android.graphics.ImageFormat}, which can be queried * with {@link android.hardware.Camera.Parameters#getPreviewFormat()}. * If {@link android.hardware.Camera.Parameters#setPreviewFormat(int)} * is never called, the default will be the YCbCr_420_SP * (NV21) format. - * @param camera The Camera service object. + * @param camera the Camera service object. */ void onPreviewFrame(byte[] data, Camera camera); }; /** - * Start drawing preview frames to the surface. + * Starts capturing and drawing preview frames to the screen. + * Preview will not actually start until a surface is supplied with + * {@link #setPreviewDisplay(SurfaceHolder)}. + * + * <p>If {@link #setPreviewCallback(Camera.PreviewCallback)}, + * {@link #setOneShotPreviewCallback(Camera.PreviewCallback)}, or + * {@link #setPreviewCallbackWithBuffer(Camera.PreviewCallback)} were + * called, {@link Camera.PreviewCallback#onPreviewFrame(byte[], Camera)} + * will be called when preview data becomes available. */ public native final void startPreview(); /** - * Stop drawing preview frames to the surface. + * Stops capturing and drawing preview frames to the surface, and + * resets the camera for a future call to {@link #startPreview()}. */ public native final void stopPreview(); @@ -272,11 +393,13 @@ public class Camera { public native final boolean previewEnabled(); /** - * Can be called at any time to instruct the camera to use a callback for - * each preview frame in addition to displaying it. + * Installs a callback to be invoked for every preview frame in addition + * to displaying them on the screen. The callback will be repeatedly called + * for as long as preview is active. This method can be called at any time, + * even while preview is live. Any other preview callbacks are overridden. * - * @param cb A callback object that receives a copy of each preview frame. - * Pass null to stop receiving callbacks at any time. + * @param cb a callback object that receives a copy of each preview frame, + * or null to stop receiving callbacks. */ public final void setPreviewCallback(PreviewCallback cb) { mPreviewCallback = cb; @@ -288,10 +411,13 @@ public class Camera { } /** - * Installs a callback to retrieve a single preview frame, after which the - * callback is cleared. + * Installs a callback to be invoked for the next preview frame in addition + * to displaying it on the screen. After one invocation, the callback is + * cleared. This method can be called any time, even when preview is live. + * Any other preview callbacks are overridden. * - * @param cb A callback object that receives a copy of the preview frame. + * @param cb a callback object that receives a copy of the next preview frame, + * or null to stop receiving callbacks. */ public final void setOneShotPreviewCallback(PreviewCallback cb) { mPreviewCallback = cb; @@ -303,17 +429,24 @@ public class Camera { private native final void setHasPreviewCallback(boolean installed, boolean manualBuffer); /** - * Installs a callback which will get called as long as there are buffers in the - * preview buffer queue, which minimizes dynamic allocation of preview buffers. + * Installs a callback to be invoked for every preview frame, using buffers + * supplied with {@link #addCallbackBuffer(byte[])}, in addition to + * displaying them on the screen. The callback will be repeatedly called + * for as long as preview is active and buffers are available. + * Any other preview callbacks are overridden. * - * Apps must call addCallbackBuffer to explicitly register the buffers to use, or no callbacks - * will be received. addCallbackBuffer may be safely called before or after - * a call to setPreviewCallbackWithBuffer with a non-null callback parameter. + * <p>The purpose of this method is to improve preview efficiency and frame + * rate by allowing preview frame memory reuse. You must call + * {@link #addCallbackBuffer(byte[])} at some point -- before or after + * calling this method -- or no callbacks will received. * - * The buffer queue will be cleared upon any calls to setOneShotPreviewCallback, - * setPreviewCallback, or to this method with a null callback parameter. + * The buffer queue will be cleared if this method is called with a null + * callback, {@link #setPreviewCallback(Camera.PreviewCallback)} is called, + * or {@link #setOneShotPreviewCallback(Camera.PreviewCallback)} is called. * - * @param cb A callback object that receives a copy of the preview frame. A null value will clear the queue. + * @param cb a callback object that receives a copy of the preview frame, + * or null to stop receiving callbacks and clear the buffer queue. + * @see #addCallbackBuffer(byte[]) */ public final void setPreviewCallbackWithBuffer(PreviewCallback cb) { mPreviewCallback = cb; @@ -325,21 +458,27 @@ public class Camera { /** * Adds a pre-allocated buffer to the preview callback buffer queue. * Applications can add one or more buffers to the queue. When a preview - * frame arrives and there is still available buffer, buffer will be filled - * and it is removed from the queue. Then preview callback is invoked with - * the buffer. If a frame arrives and there is no buffer left, the frame is - * discarded. Applications should add the buffers back when they finish the - * processing. + * frame arrives and there is still at least one available buffer, the + * buffer will be used and removed from the queue. Then preview callback is + * invoked with the buffer. If a frame arrives and there is no buffer left, + * the frame is discarded. Applications should add buffers back when they + * finish processing the data in them. * - * The image format of the callback buffer can be read from {@link - * android.hardware.Camera.Parameters#getPreviewFormat()}. bitsPerPixel can - * be read from {@link android.graphics.ImageFormat#getBitsPerPixel(int)}. - * Preview width and height can be determined from getPreviewSize. + * <p>The size of the buffer is determined by multiplying the preview + * image width, height, and bytes per pixel. The width and height can be + * read from {@link Camera.Parameters#getPreviewSize()}. Bytes per pixel + * can be computed from + * {@link android.graphics.ImageFormat#getBitsPerPixel(int)} / 8, + * using the image format from {@link Camera.Parameters#getPreviewFormat()}. * - * Alternatively, a buffer from a previous callback may be passed in or used - * to determine the size of new preview frame buffers. + * <p>This method is only necessary when + * {@link #setPreviewCallbackWithBuffer(PreviewCallback)} is used. When + * {@link #setPreviewCallback(PreviewCallback)} or + * {@link #setOneShotPreviewCallback(PreviewCallback)} are used, buffers + * are automatically allocated. * - * @param callbackBuffer The buffer to register. Size should be width * height * bitsPerPixel / 8. + * @param callbackBuffer the buffer to add to the queue. + * The size should be width * height * bits_per_pixel / 8. * @see #setPreviewCallbackWithBuffer(PreviewCallback) */ public native final void addCallbackBuffer(byte[] callbackBuffer); @@ -438,7 +577,8 @@ public class Camera { } /** - * Handles the callback for the camera auto focus. + * Callback interface used to notify on completion of 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 @@ -446,13 +586,15 @@ public class Camera { * {@code android.hardware.camera.autofocus} feature, in the * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> * manifest element.</p> + * + * @see #autoFocus(AutoFocusCallback) */ public interface AutoFocusCallback { /** - * Callback for the camera auto focus. If the camera does not support - * auto-focus and autoFocus is called, onAutoFocus will be called - * immediately with success. + * Called when the camera auto focus completes. If the camera does not + * support auto-focus and autoFocus is called, onAutoFocus will be + * called immediately with success. * * @param success true if focus was successful, false if otherwise * @param camera the Camera service object @@ -461,23 +603,28 @@ public class Camera { }; /** - * Starts auto-focus function and registers a callback function to run when - * camera is focused. Only valid after startPreview() has been called. - * Applications should call {@link - * android.hardware.Camera.Parameters#getFocusMode()} to determine if this - * method should be called. If the camera does not support auto-focus, it is - * a no-op and {@link AutoFocusCallback#onAutoFocus(boolean, Camera)} + * Starts camera auto-focus and registers a callback function to run when + * the camera is focused. This method is only valid when preview is active + * (between {@link #startPreview()} and before {@link #stopPreview()}). + * + * <p>Callers should check + * {@link android.hardware.Camera.Parameters#getFocusMode()} to determine if + * this method should be called. If the camera does not support auto-focus, + * it is a no-op and {@link AutoFocusCallback#onAutoFocus(boolean, Camera)} * callback will be called immediately. + * * <p>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> + * * <p>If the current flash mode is not * {@link android.hardware.Camera.Parameters#FLASH_MODE_OFF}, flash may be - * fired during auto-focus depending on the driver.<p> + * fired during auto-focus, depending on the driver and camera hardware.<p> * * @param cb the callback to run + * @see #cancelAutoFocus() */ public final void autoFocus(AutoFocusCallback cb) { @@ -487,10 +634,12 @@ public class Camera { private native final void native_autoFocus(); /** - * Cancels auto-focus function. If the auto-focus is still in progress, - * this function will cancel it. Whether the auto-focus is in progress - * or not, this function will return the focus position to the default. + * Cancels any auto-focus function in progress. + * Whether or not auto-focus is currently in progress, + * this function will return the focus position to the default. * If the camera does not support auto-focus, this is a no-op. + * + * @see #autoFocus(Camera.AutoFocusCallback) */ public final void cancelAutoFocus() { @@ -500,23 +649,32 @@ public class Camera { private native final void native_cancelAutoFocus(); /** - * An interface which contains a callback for the shutter closing after taking a picture. + * Callback interface used to signal the moment of actual image capture. + * + * @see #takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback) */ public interface ShutterCallback { /** - * Can be used to play a shutter sound as soon as the image has been captured, but before - * the data is available. + * Called as near as possible to the moment when a photo is captured + * from the sensor. This is a good opportunity to play a shutter sound + * or give other feedback of camera operation. This may be some time + * after the photo was triggered, but some time before the actual data + * is available. */ void onShutter(); } /** - * Handles the callback for when a picture is taken. + * Callback interface used to supply image data from a photo capture. + * + * @see #takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback) */ public interface PictureCallback { /** - * Callback for when a picture is taken. + * Called when image data is available after a picture is taken. + * The format of the data depends on the context of the callback + * and {@link Camera.Parameters} settings. * * @param data a byte array of the picture data * @param camera the Camera service object @@ -525,24 +683,9 @@ public class Camera { }; /** - * Triggers an asynchronous image capture. The camera service will initiate - * a series of callbacks to the application as the image capture progresses. - * The shutter callback occurs after the image is captured. This can be used - * to trigger a sound to let the user know that image has been captured. The - * raw callback occurs when the raw image data is available (NOTE: the data - * may be null if the hardware does not have enough memory to make a copy). - * The jpeg callback occurs when the compressed image is available. If the - * application does not need a particular callback, a null can be passed - * instead of a callback method. + * Equivalent to takePicture(shutter, raw, null, jpeg). * - * This method is only valid after {@link #startPreview()} has been called. - * This method will stop the preview. Applications should not call {@link - * #stopPreview()} before this. After jpeg callback is received, - * applications can call {@link #startPreview()} to restart the preview. - * - * @param shutter callback after the image is captured, may be null - * @param raw callback with raw image data, may be null - * @param jpeg callback with jpeg image data, may be null + * @see #takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback) */ public final void takePicture(ShutterCallback shutter, PictureCallback raw, PictureCallback jpeg) { @@ -563,15 +706,18 @@ public class Camera { * application does not need a particular callback, a null can be passed * instead of a callback method. * - * This method is only valid after {@link #startPreview()} has been called. - * This method will stop the preview. Applications should not call {@link - * #stopPreview()} before this. After jpeg callback is received, - * applications can call {@link #startPreview()} to restart the preview. + * <p>This method is only valid when preview is active (after + * {@link #startPreview()}). Preview will be stopped after the image is + * taken; callers must call {@link #startPreview()} again if they want to + * re-start preview or take more pictures. + * + * <p>After calling this method, you must not call {@link #startPreview()} + * or take another picture until the JPEG callback has returned. * - * @param shutter callback after the image is captured, may be null - * @param raw callback with raw image data, may be null + * @param shutter the callback for image capture moment, or null + * @param raw the callback for raw (uncompressed) image data, or null * @param postview callback with postview image data, may be null - * @param jpeg callback with jpeg image data, may be null + * @param jpeg the callback for JPEG image data, or null */ public final void takePicture(ShutterCallback shutter, PictureCallback raw, PictureCallback postview, PictureCallback jpeg) { @@ -583,26 +729,29 @@ public class Camera { } /** - * Zooms to the requested value smoothly. Driver will notify {@link + * Zooms to the requested value smoothly. The driver will notify {@link * OnZoomChangeListener} of the zoom value and whether zoom is stopped at * the time. For example, suppose the current zoom is 0 and startSmoothZoom - * is called with value 3. Method onZoomChange will be called three times - * with zoom value 1, 2, and 3. The applications can call {@link - * #stopSmoothZoom} to stop the zoom earlier. The applications should not - * call startSmoothZoom again or change the zoom value before zoom stops. If - * the passing zoom value equals to the current zoom value, no zoom callback - * will be generated. This method is supported if {@link - * android.hardware.Camera.Parameters#isSmoothZoomSupported} is true. + * is called with value 3. The + * {@link Camera.OnZoomChangeListener#onZoomChange(int, boolean, Camera)} + * method will be called three times with zoom values 1, 2, and 3. + * Applications can call {@link #stopSmoothZoom} to stop the zoom earlier. + * Applications should not call startSmoothZoom again or change the zoom + * value before zoom stops. If the supplied zoom value equals to the current + * zoom value, no zoom callback will be generated. This method is supported + * if {@link android.hardware.Camera.Parameters#isSmoothZoomSupported} + * returns true. * * @param value zoom value. The valid range is 0 to {@link * android.hardware.Camera.Parameters#getMaxZoom}. * @throws IllegalArgumentException if the zoom value is invalid. * @throws RuntimeException if the method fails. + * @see #setZoomChangeListener(OnZoomChangeListener) */ public native final void startSmoothZoom(int value); /** - * Stops the smooth zoom. The applications should wait for the {@link + * Stops the smooth zoom. Applications should wait for the {@link * OnZoomChangeListener} to know when the zoom is actually stopped. This * method is supported if {@link * android.hardware.Camera.Parameters#isSmoothZoomSupported} is true. @@ -649,20 +798,21 @@ public class Camera { public native final void setDisplayOrientation(int degrees); /** - * Interface for a callback to be invoked when zoom value changes. + * Callback interface for zoom changes during a smooth zoom operation. + * + * @see #setZoomChangeListener(OnZoomChangeListener) + * @see #startSmoothZoom(int) */ public interface OnZoomChangeListener { /** - * Called when the zoom value has changed. + * Called when the zoom value has changed during a smooth zoom. * * @param zoomValue the current zoom value. In smooth zoom mode, camera * calls this for every new zoom value. * @param stopped whether smooth zoom is stopped. If the value is true, * this is the last zoom update for the application. - * * @param camera the Camera service object - * @see #startSmoothZoom(int) */ void onZoomChange(int zoomValue, boolean stopped, Camera camera); }; @@ -679,15 +829,25 @@ public class Camera { mZoomListener = listener; } - // These match the enum in include/ui/Camera.h - /** Unspecified camerar error. @see #ErrorCallback */ + // Error codes match the enum in include/ui/Camera.h + + /** + * Unspecified camera error. + * @see Camera.ErrorCallback + */ public static final int CAMERA_ERROR_UNKNOWN = 1; - /** Media server died. In this case, the application must release the - * Camera object and instantiate a new one. @see #ErrorCallback */ + + /** + * Media server died. In this case, the application must release the + * Camera object and instantiate a new one. + * @see Camera.ErrorCallback + */ public static final int CAMERA_ERROR_SERVER_DIED = 100; /** - * Handles the camera error callback. + * Callback interface for camera error notification. + * + * @see #setErrorCallback(ErrorCallback) */ public interface ErrorCallback { @@ -705,7 +865,7 @@ public class Camera { /** * Registers a callback to be invoked when an error occurs. - * @param cb the callback to run + * @param cb The callback to run */ public final void setErrorCallback(ErrorCallback cb) { @@ -716,16 +876,21 @@ public class Camera { private native final String native_getParameters(); /** - * Sets the Parameters for pictures from this Camera service. + * Changes the settings for this Camera service. * * @param params the Parameters to use for this Camera service + * @see #getParameters() */ public void setParameters(Parameters params) { native_setParameters(params.flatten()); } /** - * Returns the picture Parameters for this Camera service. + * Returns the current settings for this Camera service. + * If modifications are made to the returned Parameters, they must be passed + * to {@link #setParameters(Camera.Parameters)} to take effect. + * + * @see #setParameters(Camera.Parameters) */ public Parameters getParameters() { Parameters p = new Parameters(); @@ -735,7 +900,7 @@ public class Camera { } /** - * Handles the picture size (dimensions). + * Image size (width and height dimensions). */ public class Size { /** @@ -774,18 +939,21 @@ public class Camera { }; /** - * Handles the parameters for pictures created by a Camera service. + * Camera service settings. * * <p>To make camera parameters take effect, applications have to call - * Camera.setParameters. For example, after setWhiteBalance is called, white - * balance is not changed until Camera.setParameters() is called. + * {@link Camera#setParameters(Camera.Parameters)}. For example, after + * {@link Camera.Parameters#setWhiteBalance} is called, white balance is not + * actually changed until {@link Camera#setParameters(Camera.Parameters)} + * is called with the changed parameters object. * * <p>Different devices may have different camera capabilities, such as * picture size or flash modes. The application should query the camera * capabilities before setting parameters. For example, the application - * should call getSupportedColorEffects before calling setEffect. If the - * camera does not support color effects, getSupportedColorEffects will - * return null. + * should call {@link Camera.Parameters#getSupportedColorEffects()} before + * calling {@link Camera.Parameters#setColorEffect(String)}. If the + * camera does not support color effects, + * {@link Camera.Parameters#getSupportedColorEffects()} will return null. */ public class Parameters { // Parameter keys to communicate with the camera driver. |