Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "COMMENT-ONLY change to clarify Camera documentation." into froyo

Browse Source
This commit is contained in:
Dan Egnor
2010-07-19 18:14:50 -07:00
committed by Android (Google) Code Review
parent 85e7ae9bbb bfcbeffc54
commit 9bc4039a58
1 changed files with 313 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

459
core/java/android/hardware/Camera.java
View File

@@ -32,23 +32,79 @@ import android.os.Looper;
import android.os.Message; import android.os.Message;
/** /**
* The Camera class is used to connect/disconnect with the camera service, * The Camera class is used to set image capture settings, start/stop preview,
* set capture settings, start/stop preview, snap a picture, and retrieve * snap pictures, and retrieve frames for encoding for video. This class is a
* frames for encoding for video. * client for the Camera service, which manages the actual camera hardware.
* <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 * <p>To access the device camera, you must declare the
* {@link android.Manifest.permission#CAMERA} permission in your Android * {@link android.Manifest.permission#CAMERA} permission in your Android
* Manifest. Also be sure to include the * Manifest. Also be sure to include the
* <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature></a> * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;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 * For example, if you use the camera and auto-focus feature, your Manifest
* should include the following:</p> * should include the following:</p>
* <pre> &lt;uses-permission android:name="android.permission.CAMERA" /> * <pre> &lt;uses-permission android:name="android.permission.CAMERA" />
* &lt;uses-feature android:name="android.hardware.camera" /> * &lt;uses-feature android:name="android.hardware.camera" />
* &lt;uses-feature android:name="android.hardware.camera.autofocus" /></pre> * &lt;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()}.
*
* <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()} 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 * <p class="caution"><strong>Caution:</strong> Different Android-powered devices
* may have different hardware specifications, such as megapixel ratings and * may have different hardware specifications, such as megapixel ratings and
* auto-focus capabilities. In order for your application to be compatible with * auto-focus capabilities. In order for your application to be compatible with
@@ -84,7 +140,26 @@ public class Camera {
private boolean mWithBuffer; private boolean mWithBuffer;
/** /**
* Returns a new Camera object. * Creates a new Camera object.
*
* <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.
*
* <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.
*
* @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() { public static Camera open() {
return new Camera(); return new Camera();
@@ -120,56 +195,83 @@ public class Camera {
/** /**
* Disconnects and releases the Camera object resources. * 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() { public final void release() {
native_release(); native_release();
} }
/** /**
* Reconnect to the camera after passing it to MediaRecorder. To save * Unlocks the camera to allow another process to access it.
* setup/teardown time, a client of Camera can pass an initialized Camera * Normally, the camera is locked to the process with an active Camera
* object to a MediaRecorder to use for video recording. Once the * object until {@link #release()} is called. To allow rapid handoff
* MediaRecorder is done with the Camera, this method can be used to * between processes, you can call this method to release the camera
* re-establish a connection with the camera hardware. NOTE: The Camera * temporarily for another process to use; once the other process is done
* object must first be unlocked by the process that owns it before it * you can call {@link #reconnect()} to reclaim the camera.
* can be connected to another process.
* *
* @throws IOException if the method fails. * <p>This must be done before calling
*/ * {@link android.media.MediaRecorder#setCamera(Camera)}.
public native final void reconnect() throws IOException;
/**
* 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.
* *
* @throws RuntimeException if the method fails. * <p>If you are not recording video, you probably do not need this method.
*/
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.
* *
* @throws RuntimeException if the method fails. * @throws RuntimeException if the camera cannot be unlocked.
*/ */
public native final void unlock(); public native final void unlock();
/** /**
* Sets the SurfaceHolder to be used for a picture preview. If the surface * Re-locks the camera to prevent other processes from accessing it.
* changed since the last call, the screen will blank. Nothing happens * Camera objects are locked by default unless {@link #unlock()} is
* if the same surface is re-set. * called. Normally {@link #reconnect()} is used instead.
* *
* @param holder the SurfaceHolder upon which to place the picture preview * <p>If you are not recording video, you probably do not need this method.
* @throws IOException if the method fails. *
* @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();
/**
* 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.
*
* <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 reconnect() throws IOException;
/**
* 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 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 { public final void setPreviewDisplay(SurfaceHolder holder) throws IOException {
if (holder != null) { if (holder != null) {
@@ -182,31 +284,47 @@ public class Camera {
private native final void setPreviewDisplay(Surface surface); 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 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()} 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 * by {@link android.graphics.ImageFormat}, which can be queried
* with {@link android.hardware.Camera.Parameters#getPreviewFormat()}. * with {@link android.hardware.Camera.Parameters#getPreviewFormat()}.
* If {@link android.hardware.Camera.Parameters#setPreviewFormat(int)} * If {@link android.hardware.Camera.Parameters#setPreviewFormat(int)}
* is never called, the default will be the YCbCr_420_SP * is never called, the default will be the YCbCr_420_SP
* (NV21) format. * (NV21) format.
* @param camera The Camera service object. * @param camera the Camera service object.
*/ */
void onPreviewFrame(byte[] data, Camera camera); 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(); 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(); public native final void stopPreview();
@@ -219,11 +337,13 @@ public class Camera {
public native final boolean previewEnabled(); public native final boolean previewEnabled();
/** /**
* Can be called at any time to instruct the camera to use a callback for * Installs a callback to be invoked for every preview frame in addition
* each preview frame in addition to displaying it. * 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. * @param cb a callback object that receives a copy of each preview frame,
* Pass null to stop receiving callbacks at any time. * or null to stop receiving callbacks.
*/ */
public final void setPreviewCallback(PreviewCallback cb) { public final void setPreviewCallback(PreviewCallback cb) {
mPreviewCallback = cb; mPreviewCallback = cb;
@@ -235,10 +355,13 @@ public class Camera {
} }
/** /**
* Installs a callback to retrieve a single preview frame, after which the * Installs a callback to be invoked for the next preview frame in addition
* callback is cleared. * 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) { public final void setOneShotPreviewCallback(PreviewCallback cb) {
mPreviewCallback = cb; mPreviewCallback = cb;
@@ -250,17 +373,24 @@ public class Camera {
private native final void setHasPreviewCallback(boolean installed, boolean manualBuffer); private native final void setHasPreviewCallback(boolean installed, boolean manualBuffer);
/** /**
* Installs a callback which will get called as long as there are buffers in the * Installs a callback to be invoked for every preview frame, using buffers
* preview buffer queue, which minimizes dynamic allocation of preview 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 * <p>The purpose of this method is to improve preview efficiency and frame
* will be received. addCallbackBuffer may be safely called before or after * rate by allowing preview frame memory reuse. You must call
* a call to setPreviewCallbackWithBuffer with a non-null callback parameter. * {@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, * The buffer queue will be cleared if this method is called with a null
* setPreviewCallback, or to this method with a null callback parameter. * 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) { public final void setPreviewCallbackWithBuffer(PreviewCallback cb) {
mPreviewCallback = cb; mPreviewCallback = cb;
@@ -272,21 +402,27 @@ public class Camera {
/** /**
* Adds a pre-allocated buffer to the preview callback buffer queue. * Adds a pre-allocated buffer to the preview callback buffer queue.
* Applications can add one or more buffers to the queue. When a preview * 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 * frame arrives and there is still at least one available buffer, the
* and it is removed from the queue. Then preview callback is invoked with * buffer will be used and removed from the queue. Then preview callback is
* the buffer. If a frame arrives and there is no buffer left, the frame is * invoked with the buffer. If a frame arrives and there is no buffer left,
* discarded. Applications should add the buffers back when they finish the * the frame is discarded. Applications should add buffers back when they
* processing. * finish processing the data in them.
* *
* The image format of the callback buffer can be read from {@link * <p>The size of the buffer is determined by multiplying the preview
* android.hardware.Camera.Parameters#getPreviewFormat()}. bitsPerPixel can * image width, height, and bytes per pixel. The width and height can be
* be read from {@link android.graphics.ImageFormat#getBitsPerPixel(int)}. * read from {@link Camera.Parameters#getPreviewSize()}. Bytes per pixel
* Preview width and height can be determined from getPreviewSize. * 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 * <p>This method is only necessary when
* to determine the size of new preview frame buffers. * {@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) * @see #setPreviewCallbackWithBuffer(PreviewCallback)
*/ */
public native final void addCallbackBuffer(byte[] callbackBuffer); public native final void addCallbackBuffer(byte[] callbackBuffer);
@@ -385,7 +521,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" * <p>Devices that do not support auto-focus will receive a "fake"
* callback to this interface. If your application needs auto-focus and * callback to this interface. If your application needs auto-focus and
* should not be installed on devices <em>without</em> auto-focus, you must * should not be installed on devices <em>without</em> auto-focus, you must
@@ -393,13 +530,15 @@ public class Camera {
* {@code android.hardware.camera.autofocus} feature, in the * {@code android.hardware.camera.autofocus} feature, in the
* <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature></a> * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature></a>
* manifest element.</p> * manifest element.</p>
*
* @see #autoFocus(AutoFocusCallback)
*/ */
public interface AutoFocusCallback public interface AutoFocusCallback
{ {
/** /**
* Callback for the camera auto focus. If the camera does not support * Called when the camera auto focus completes. If the camera does not
* auto-focus and autoFocus is called, onAutoFocus will be called * support auto-focus and autoFocus is called, onAutoFocus will be
* immediately with success. * called immediately with success.
* *
* @param success true if focus was successful, false if otherwise * @param success true if focus was successful, false if otherwise
* @param camera the Camera service object * @param camera the Camera service object
@@ -408,23 +547,28 @@ public class Camera {
}; };
/** /**
* Starts auto-focus function and registers a callback function to run when * Starts camera auto-focus and registers a callback function to run when
* camera is focused. Only valid after startPreview() has been called. * the camera is focused. This method is only valid when preview is active
* Applications should call {@link * (between {@link #startPreview()} and before {@link #stopPreview()}).
* android.hardware.Camera.Parameters#getFocusMode()} to determine if this *
* method should be called. If the camera does not support auto-focus, it is * <p>Callers should check
* a no-op and {@link AutoFocusCallback#onAutoFocus(boolean, Camera)} * {@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. * callback will be called immediately.
*
* <p>If your application should not be installed * <p>If your application should not be installed
* on devices without auto-focus, you must declare that your application * on devices without auto-focus, you must declare that your application
* uses auto-focus with the * uses auto-focus with the
* <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature></a> * <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">&lt;uses-feature></a>
* manifest element.</p> * manifest element.</p>
*
* <p>If the current flash mode is not * <p>If the current flash mode is not
* {@link android.hardware.Camera.Parameters#FLASH_MODE_OFF}, flash may be * {@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 * @param cb the callback to run
* @see #cancelAutoFocus()
*/ */
public final void autoFocus(AutoFocusCallback cb) public final void autoFocus(AutoFocusCallback cb)
{ {
@@ -434,10 +578,12 @@ public class Camera {
private native final void native_autoFocus(); private native final void native_autoFocus();
/** /**
* Cancels auto-focus function. If the auto-focus is still in progress, * Cancels any auto-focus function in progress.
* this function will cancel it. Whether the auto-focus is in progress * Whether or not auto-focus is currently in progress,
* or not, this function will return the focus position to the default. * this function will return the focus position to the default.
* If the camera does not support auto-focus, this is a no-op. * If the camera does not support auto-focus, this is a no-op.
*
* @see #autoFocus(Camera.AutoFocusCallback)
*/ */
public final void cancelAutoFocus() public final void cancelAutoFocus()
{ {
@@ -447,23 +593,32 @@ public class Camera {
private native final void native_cancelAutoFocus(); 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 public interface ShutterCallback
{ {
/** /**
* Can be used to play a shutter sound as soon as the image has been captured, but before * Called as near as possible to the moment when a photo is captured
* the data is available. * 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(); 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 { 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 data a byte array of the picture data
* @param camera the Camera service object * @param camera the Camera service object
@@ -472,23 +627,9 @@ public class Camera {
}; };
/** /**
* Triggers an asynchronous image capture. The camera service will initiate * Equivalent to takePicture(shutter, raw, null, jpeg).
* 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.
* *
* This method will stop the preview. Applications should not call {@link * @see #takePicture(ShutterCallback, PictureCallback, PictureCallback, PictureCallback)
* #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
*/ */
public final void takePicture(ShutterCallback shutter, PictureCallback raw, public final void takePicture(ShutterCallback shutter, PictureCallback raw,
PictureCallback jpeg) { PictureCallback jpeg) {
@@ -509,14 +650,18 @@ public class Camera {
* application does not need a particular callback, a null can be passed * application does not need a particular callback, a null can be passed
* instead of a callback method. * instead of a callback method.
* *
* This method will stop the preview. Applications should not call {@link * <p>This method is only valid when preview is active (after
* #stopPreview()} before this. After jpeg callback is received, * {@link #startPreview()}). Preview will be stopped after the image is
* applications can call {@link #startPreview()} to restart the preview. * taken; callers must call {@link #startPreview()} again if they want to
* re-start preview or take more pictures.
* *
* @param shutter callback after the image is captured, may be null * <p>After calling this method, you must not call {@link #startPreview()}
* @param raw callback with raw image data, may be null * or take another picture until the JPEG callback has returned.
*
* @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 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, public final void takePicture(ShutterCallback shutter, PictureCallback raw,
PictureCallback postview, PictureCallback jpeg) { PictureCallback postview, PictureCallback jpeg) {
@@ -528,26 +673,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 * OnZoomChangeListener} of the zoom value and whether zoom is stopped at
* the time. For example, suppose the current zoom is 0 and startSmoothZoom * the time. For example, suppose the current zoom is 0 and startSmoothZoom
* is called with value 3. Method onZoomChange will be called three times * is called with value 3. The
* with zoom value 1, 2, and 3. The applications can call {@link * {@link Camera.OnZoomChangeListener#onZoomChange(int, boolean, Camera)}
* #stopSmoothZoom} to stop the zoom earlier. The applications should not * method will be called three times with zoom values 1, 2, and 3.
* call startSmoothZoom again or change the zoom value before zoom stops. If * Applications can call {@link #stopSmoothZoom} to stop the zoom earlier.
* the passing zoom value equals to the current zoom value, no zoom callback * Applications should not call startSmoothZoom again or change the zoom
* will be generated. This method is supported if {@link * value before zoom stops. If the supplied zoom value equals to the current
* android.hardware.Camera.Parameters#isSmoothZoomSupported} is true. * 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 * @param value zoom value. The valid range is 0 to {@link
* android.hardware.Camera.Parameters#getMaxZoom}. * android.hardware.Camera.Parameters#getMaxZoom}.
* @throws IllegalArgumentException if the zoom value is invalid. * @throws IllegalArgumentException if the zoom value is invalid.
* @throws RuntimeException if the method fails. * @throws RuntimeException if the method fails.
* @see #setZoomChangeListener(OnZoomChangeListener)
*/ */
public native final void startSmoothZoom(int value); 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 * OnZoomChangeListener} to know when the zoom is actually stopped. This
* method is supported if {@link * method is supported if {@link
* android.hardware.Camera.Parameters#isSmoothZoomSupported} is true. * android.hardware.Camera.Parameters#isSmoothZoomSupported} is true.
@@ -572,20 +720,21 @@ public class Camera {
public native final void setDisplayOrientation(int degrees); 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 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 * @param zoomValue the current zoom value. In smooth zoom mode, camera
* calls this for every new zoom value. * calls this for every new zoom value.
* @param stopped whether smooth zoom is stopped. If the value is true, * @param stopped whether smooth zoom is stopped. If the value is true,
* this is the last zoom update for the application. * this is the last zoom update for the application.
*
* @param camera the Camera service object * @param camera the Camera service object
* @see #startSmoothZoom(int)
*/ */
void onZoomChange(int zoomValue, boolean stopped, Camera camera); void onZoomChange(int zoomValue, boolean stopped, Camera camera);
}; };
@@ -602,15 +751,25 @@ public class Camera {
mZoomListener = listener; mZoomListener = listener;
} }
// These match the enum in include/ui/Camera.h // Error codes match the enum in include/ui/Camera.h
/** Unspecified camerar error. @see #ErrorCallback */
/**
* Unspecified camera error.
* @see Camera.ErrorCallback
*/
public static final int CAMERA_ERROR_UNKNOWN = 1; 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; 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 public interface ErrorCallback
{ {
@@ -628,7 +787,7 @@ public class Camera {
/** /**
* Registers a callback to be invoked when an error occurs. * 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) public final void setErrorCallback(ErrorCallback cb)
{ {
@@ -639,16 +798,21 @@ public class Camera {
private native final String native_getParameters(); 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 * @param params the Parameters to use for this Camera service
* @see #getParameters()
*/ */
public void setParameters(Parameters params) { public void setParameters(Parameters params) {
native_setParameters(params.flatten()); 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() { public Parameters getParameters() {
Parameters p = new Parameters(); Parameters p = new Parameters();
@@ -658,7 +822,7 @@ public class Camera {
} }
/** /**
* Handles the picture size (dimensions). * Image size (width and height dimensions).
*/ */
public class Size { public class Size {
/** /**
@@ -697,18 +861,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 * <p>To make camera parameters take effect, applications have to call
* Camera.setParameters. For example, after setWhiteBalance is called, white * {@link Camera#setParameters(Camera.Parameters)}. For example, after
* balance is not changed until Camera.setParameters() is called. * {@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 * <p>Different devices may have different camera capabilities, such as
* picture size or flash modes. The application should query the camera * picture size or flash modes. The application should query the camera
* capabilities before setting parameters. For example, the application * capabilities before setting parameters. For example, the application
* should call getSupportedColorEffects before calling setEffect. If the * should call {@link Camera.Parameters#getSupportedColorEffects()} before
* camera does not support color effects, getSupportedColorEffects will * calling {@link Camera.Parameters#setColorEffect(String)}. If the
* return null. * camera does not support color effects,
* {@link Camera.Parameters#getSupportedColorEffects()} will return null.
*/ */
public class Parameters { public class Parameters {
// Parameter keys to communicate with the camera driver. // Parameter keys to communicate with the camera driver.