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()}.
+ *
+ * <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
* may have different hardware specifications, such as megapixel ratings and
* auto-focus capabilities. In order for your application to be compatible with
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() {
return new 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)}.
+ *
+ * <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 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.
*
- * @param holder the SurfaceHolder upon which to place the picture preview
- * @throws IOException if the method fails.
+ * <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 {
if (holder != null) {
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()} 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();
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;
}
/**
- * 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;
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;
/**
* 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);
}
/**
- * 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
* {@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
};
/**
- * 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)
{
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()
{
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
};
/**
- * 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.
- *
- * 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.
+ * Equivalent to takePicture(shutter, raw, null, jpeg).
*
- * @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) {
* 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
- * #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.
*
- * @param shutter callback after the image is captured, may be null
- * @param raw callback with raw image data, may be null
+ * <p>After calling this method, you must not call {@link #startPreview()}
+ * 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 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) {
}
/**
- * 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.
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);
};
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
{
/**
* 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)
{
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();
}
/**
- * Handles the picture size (dimensions).
+ * Image size (width and height dimensions).
*/
public class Size {
/**
};
/**
- * 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.
OSDN Git Service
