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 * <uses-feature> * 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:
*<uses-permission android:name="android.permission.CAMERA" /> * <uses-feature android:name="android.hardware.camera" /> * <uses-feature android:name="android.hardware.camera.autofocus" />* *
To take pictures with this class, use the following steps:
* *To quickly switch to video recording mode, use these steps:
* *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.
* *Caution: Different Android-powered devices * may have different hardware specifications, such as megapixel ratings and * auto-focus capabilities. In order for your application to be compatible with * more devices, you should not make assumptions about the device camera * specifications.
* *For more information about using cameras, read the * Camera developer guide.
*In {@link android.os.Build.VERSION_CODES#N Android N} this broadcast was removed, and * applications are recommended to use * {@link android.app.job.JobInfo.Builder JobInfo.Builder}.{@link android.app.job.JobInfo.Builder#addTriggerContentUri} * instead.
* *In {@link android.os.Build.VERSION_CODES#O Android O} this broadcast has been brought * back, but only for registered receivers. Apps that are actively running can * again listen to the broadcast if they want an immediate clear signal about a picture * being taken, however anything doing heavy work (or needing to be launched) as a result of * this should still use JobScheduler.
*/ @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) public static final String ACTION_NEW_PICTURE = "android.hardware.action.NEW_PICTURE"; /** * Broadcast Action: A new video is recorded by the camera, and the entry * of the video has been added to the media store. * {@link android.content.Intent#getData} is URI of the video. * *In {@link android.os.Build.VERSION_CODES#N Android N} this broadcast was removed, and * applications are recommended to use * {@link android.app.job.JobInfo.Builder JobInfo.Builder}.{@link android.app.job.JobInfo.Builder#addTriggerContentUri} * instead.
* *In {@link android.os.Build.VERSION_CODES#O Android O} this broadcast has been brought * back, but only for registered receivers. Apps that are actively running can * again listen to the broadcast if they want an immediate clear signal about a video * being taken, however anything doing heavy work (or needing to be launched) as a result of * this should still use JobScheduler.
*/ @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) public static final String ACTION_NEW_VIDEO = "android.hardware.action.NEW_VIDEO"; /** * Camera HAL device API version 1.0 * @hide */ public static final int CAMERA_HAL_API_VERSION_1_0 = 0x100; /** * A constant meaning the normal camera connect/open will be used. */ private static final int CAMERA_HAL_API_VERSION_NORMAL_CONNECT = -2; /** * Used to indicate HAL version un-specified. */ private static final int CAMERA_HAL_API_VERSION_UNSPECIFIED = -1; /** * Hardware face detection. It does not use much CPU. */ private static final int CAMERA_FACE_DETECTION_HW = 0; /** * Software face detection. It uses some CPU. */ private static final int CAMERA_FACE_DETECTION_SW = 1; /** * Returns the number of physical cameras available on this device. */ public native static int getNumberOfCameras(); /** * Returns the information about a particular camera. * If {@link #getNumberOfCameras()} returns N, the valid id is 0 to N-1. */ public static void getCameraInfo(int cameraId, CameraInfo cameraInfo) { _getCameraInfo(cameraId, cameraInfo); IBinder b = ServiceManager.getService(Context.AUDIO_SERVICE); IAudioService audioService = IAudioService.Stub.asInterface(b); try { if (audioService.isCameraSoundForced()) { // Only set this when sound is forced; otherwise let native code // decide. cameraInfo.canDisableShutterSound = false; } } catch (RemoteException e) { Log.e(TAG, "Audio service is unavailable for queries"); } } private native static void _getCameraInfo(int cameraId, CameraInfo cameraInfo); /** * Information about a camera * * @deprecated We recommend using the new {@link android.hardware.camera2} API for new * applications. */ @Deprecated public static class CameraInfo { /** * The facing of the camera is opposite to that of the screen. */ public static final int CAMERA_FACING_BACK = 0; /** * The facing of the camera is the same as that of the screen. */ public static final int CAMERA_FACING_FRONT = 1; /** * The direction that the camera faces. It should be * CAMERA_FACING_BACK or CAMERA_FACING_FRONT. */ public int facing; /** *The orientation of the camera image. The value is the angle that the * camera image needs to be rotated clockwise so it shows correctly on * the display in its natural orientation. It should be 0, 90, 180, or 270.
* *For example, suppose a device has a naturally tall screen. The * back-facing camera sensor is mounted in landscape. You are looking at * the screen. If the top side of the camera sensor is aligned with the * right edge of the screen in natural orientation, the value should be * 90. If the top side of a front-facing camera sensor is aligned with * the right of the screen, the value should be 270.
* * @see #setDisplayOrientation(int) * @see Parameters#setRotation(int) * @see Parameters#setPreviewSize(int, int) * @see Parameters#setPictureSize(int, int) * @see Parameters#setJpegThumbnailSize(int, int) */ public int orientation; /** *Whether the shutter sound can be disabled.
* *On some devices, the camera shutter sound cannot be turned off * through {@link #enableShutterSound enableShutterSound}. This field * can be used to determine whether a call to disable the shutter sound * will succeed.
* *If this field is set to true, then a call of * {@code enableShutterSound(false)} will be successful. If set to * false, then that call will fail, and the shutter sound will be played * when {@link Camera#takePicture takePicture} is called.
*/ public boolean canDisableShutterSound; }; /** * Creates a new Camera object to access a particular hardware camera. If * the same camera is opened by other applications, this will throw a * RuntimeException. * *You must call {@link #release()} when you are done using the camera, * otherwise it will remain locked and be unavailable to other applications. * *
Your application should only have one Camera object active at a time * for a particular hardware camera. * *
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. * *
Caution: 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. * @return a new Camera object, connected, locked and ready for use. * @throws RuntimeException if opening the camera fails (for example, if the * camera is in use by another process or device policy manager has * disabled the camera). * @see android.app.admin.DevicePolicyManager#getCameraDisabled(android.content.ComponentName) */ public static Camera open(int cameraId) { return new Camera(cameraId); } /** * Creates a new Camera object to access the first back-facing camera on the * device. If the device does not have a back-facing camera, this returns * null. * @see #open(int) */ public static Camera open() { int numberOfCameras = getNumberOfCameras(); CameraInfo cameraInfo = new CameraInfo(); for (int i = 0; i < numberOfCameras; i++) { getCameraInfo(i, cameraInfo); if (cameraInfo.facing == CameraInfo.CAMERA_FACING_BACK) { return new Camera(i); } } return null; } /** * Creates a new Camera object to access a particular hardware camera with * given hal API version. If the same camera is opened by other applications * or the hal API version is not supported by this device, this will throw a * RuntimeException. *
* You must call {@link #release()} when you are done using the camera, * otherwise it will remain locked and be unavailable to other applications. *
* Your application should only have one Camera object active at a time for * a particular hardware camera. *
* 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. *
* Caution: 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.
* @param halVersion The HAL API version this camera device to be opened as.
* @return a new Camera object, connected, locked and ready for use.
*
* @throws IllegalArgumentException if the {@code halVersion} is invalid
*
* @throws RuntimeException if opening the camera fails (for example, if the
* camera is in use by another process or device policy manager has disabled
* the camera).
*
* @see android.app.admin.DevicePolicyManager#getCameraDisabled(android.content.ComponentName)
* @see #CAMERA_HAL_API_VERSION_1_0
*
* @hide
*/
public static Camera openLegacy(int cameraId, int halVersion) {
if (halVersion < CAMERA_HAL_API_VERSION_1_0) {
throw new IllegalArgumentException("Invalid HAL version " + halVersion);
}
return new Camera(cameraId, halVersion);
}
/**
* Create a legacy camera object.
*
* @param cameraId The hardware camera to access, between 0 and
* {@link #getNumberOfCameras()}-1.
* @param halVersion The HAL API version this camera device to be opened as.
*/
private Camera(int cameraId, int halVersion) {
int err = cameraInitVersion(cameraId, halVersion);
if (checkInitErrors(err)) {
if (err == -EACCES) {
throw new RuntimeException("Fail to connect to camera service");
} else if (err == -ENODEV) {
throw new RuntimeException("Camera initialization failed");
} else if (err == -ENOSYS) {
throw new RuntimeException("Camera initialization failed because some methods"
+ " are not implemented");
} else if (err == -EOPNOTSUPP) {
throw new RuntimeException("Camera initialization failed because the hal"
+ " version is not supported by this device");
} else if (err == -EINVAL) {
throw new RuntimeException("Camera initialization failed because the input"
+ " arugments are invalid");
} else if (err == -EBUSY) {
throw new RuntimeException("Camera initialization failed because the camera"
+ " device was already opened");
} else if (err == -EUSERS) {
throw new RuntimeException("Camera initialization failed because the max"
+ " number of camera devices were already opened");
}
// Should never hit this.
throw new RuntimeException("Unknown camera error");
}
}
private int cameraInitVersion(int cameraId, int halVersion) {
mShutterCallback = null;
mRawImageCallback = null;
mJpegCallback = null;
mPreviewCallback = null;
mPostviewCallback = null;
mUsingPreviewAllocation = false;
mZoomListener = null;
Looper looper;
if ((looper = Looper.myLooper()) != null) {
mEventHandler = new EventHandler(this, looper);
} else if ((looper = Looper.getMainLooper()) != null) {
mEventHandler = new EventHandler(this, looper);
} else {
mEventHandler = null;
}
return native_setup(new WeakReference
* This acts the same as normal except that it will return
* the detailed error code if open fails instead of
* converting everything into {@code NO_INIT}. Intended to use by the camera2 shim only, do not use this for other code. You must call this as soon as you're done with the Camera object. This must be done before calling
* {@link android.media.MediaRecorder#setCamera(Camera)}. This cannot be
* called after recording starts.
*
* 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 unlock();
/**
* 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.
*
* Since API level 14, camera is automatically locked for applications in
* {@link android.media.MediaRecorder#start()}. Applications can use the
* camera (ex: zoom) after recording starts. There is no need to call this
* after recording starts or stops.
*
* 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();
/**
* 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.
*
* Since API level 14, camera is automatically locked for applications in
* {@link android.media.MediaRecorder#start()}. Applications can use the
* camera (ex: zoom) after recording starts. There is no need to call this
* after recording starts or stops.
*
* 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.
* Either a surface or surface texture is necessary for preview, and
* preview is necessary to take pictures. The same surface can be re-set
* without harm. Setting a preview surface will un-set any preview surface
* texture that was set via {@link #setPreviewTexture}.
*
* 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.
*
* 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) {
setPreviewSurface(holder.getSurface());
} else {
setPreviewSurface((Surface)null);
}
}
/**
* @hide
*/
public native final void setPreviewSurface(Surface surface) throws IOException;
/**
* Sets the {@link SurfaceTexture} to be used for live preview.
* Either a surface or surface texture is necessary for preview, and
* preview is necessary to take pictures. The same surface texture can be
* re-set without harm. Setting a preview surface texture will un-set any
* preview surface that was set via {@link #setPreviewDisplay}.
*
* This method must be called before {@link #startPreview()}. The
* one exception is that if the preview surface texture 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 texture may not otherwise change while preview is
* running.
*
* The timestamps provided by {@link SurfaceTexture#getTimestamp()} for a
* SurfaceTexture set as the preview texture have an unspecified zero point,
* and cannot be directly compared between different cameras or different
* instances of the same camera, or across multiple runs of the same
* program.
*
* If you are using the preview data to create video or still images,
* strongly consider using {@link android.media.MediaActionSound} to
* properly indicate image capture or recording start/stop to the user. If using the {@link android.graphics.ImageFormat#YV12} format,
* refer to the equations in {@link Camera.Parameters#setPreviewFormat}
* for the arrangement of the pixel data in the preview callback
* buffers.
*
* @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.
*/
void onPreviewFrame(byte[] data, Camera camera);
};
/**
* Starts capturing and drawing preview frames to the screen.
* Preview will not actually start until a surface is supplied
* with {@link #setPreviewDisplay(SurfaceHolder)} or
* {@link #setPreviewTexture(SurfaceTexture)}.
*
* 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();
/**
* Stops capturing and drawing preview frames to the surface, and
* resets the camera for a future call to {@link #startPreview()}.
*/
public final void stopPreview() {
_stopPreview();
mFaceDetectionRunning = false;
mShutterCallback = null;
mRawImageCallback = null;
mPostviewCallback = null;
mJpegCallback = null;
synchronized (mAutoFocusCallbackLock) {
mAutoFocusCallback = null;
}
mAutoFocusMoveCallback = null;
}
private native final void _stopPreview();
/**
* Return current preview state.
*
* FIXME: Unhide before release
* @hide
*/
public native final boolean previewEnabled();
/**
* 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. If you are using the preview data to create video or still images,
* strongly consider using {@link android.media.MediaActionSound} to
* properly indicate image capture or recording start/stop to the user. 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. If you are using the preview data to create video or still images,
* strongly consider using {@link android.media.MediaActionSound} to
* properly indicate image capture or recording start/stop to the user. 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. 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 if this method is called with a null
* callback, {@link #setPreviewCallback(Camera.PreviewCallback)} is called,
* or {@link #setOneShotPreviewCallback(Camera.PreviewCallback)} is
* called. If you are using the preview data to create video or still images,
* strongly consider using {@link android.media.MediaActionSound} to
* properly indicate image capture or recording start/stop to the user. For formats besides YV12, 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()}.
*
* If using the {@link android.graphics.ImageFormat#YV12} format, the
* size can be calculated using the equations listed in
* {@link Camera.Parameters#setPreviewFormat}.
*
* 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. When a supplied buffer is too small to
* hold the preview frame data, preview callback will return null and
* the buffer will be removed from the buffer queue.
*
* @param callbackBuffer the buffer to add to the queue. The size of the
* buffer must match the values described above.
* @see #setPreviewCallbackWithBuffer(PreviewCallback)
*/
public final void addCallbackBuffer(byte[] callbackBuffer)
{
_addCallbackBuffer(callbackBuffer, CAMERA_MSG_PREVIEW_FRAME);
}
/**
* Adds a pre-allocated buffer to the raw image callback buffer queue.
* Applications can add one or more buffers to the queue. When a raw image
* frame arrives and there is still at least one available buffer, the
* buffer will be used to hold the raw image data and removed from the
* queue. Then raw image callback is invoked with the buffer. If a raw
* image frame arrives but there is no buffer left, the frame is
* discarded. Applications should add buffers back when they finish
* processing the data in them by calling this method again in order
* to avoid running out of raw image callback buffers.
*
* The size of the buffer is determined by multiplying the raw image
* width, height, and bytes per pixel. The width and height can be
* read from {@link Camera.Parameters#getPictureSize()}. Bytes per pixel
* can be computed from
* {@link android.graphics.ImageFormat#getBitsPerPixel(int)} / 8,
* using the image format from {@link Camera.Parameters#getPreviewFormat()}.
*
* This method is only necessary when the PictureCallbck for raw image
* is used while calling {@link #takePicture(Camera.ShutterCallback,
* Camera.PictureCallback, Camera.PictureCallback, Camera.PictureCallback)}.
*
* Please note that by calling this method, the mode for
* application-managed callback buffers is triggered. If this method has
* never been called, null will be returned by the raw image callback since
* there is no image callback buffer available. Furthermore, When a supplied
* buffer is too small to hold the raw image data, raw image callback will
* return null and the buffer will be removed from the buffer queue.
*
* @param callbackBuffer the buffer to add to the raw image callback buffer
* queue. The size should be width * height * (bits per pixel) / 8. An
* null callbackBuffer will be ignored and won't be added to the queue.
*
* @see #takePicture(Camera.ShutterCallback,
* Camera.PictureCallback, Camera.PictureCallback, Camera.PictureCallback)}.
*
* {@hide}
*/
public final void addRawImageCallbackBuffer(byte[] callbackBuffer)
{
addCallbackBuffer(callbackBuffer, CAMERA_MSG_RAW_IMAGE);
}
private final void addCallbackBuffer(byte[] callbackBuffer, int msgType)
{
// CAMERA_MSG_VIDEO_FRAME may be allowed in the future.
if (msgType != CAMERA_MSG_PREVIEW_FRAME &&
msgType != CAMERA_MSG_RAW_IMAGE) {
throw new IllegalArgumentException(
"Unsupported message type: " + msgType);
}
_addCallbackBuffer(callbackBuffer, msgType);
}
private native final void _addCallbackBuffer(
byte[] callbackBuffer, int msgType);
/**
* Create a {@link android.renderscript RenderScript}
* {@link android.renderscript.Allocation Allocation} to use as a
* destination of preview callback frames. Use
* {@link #setPreviewCallbackAllocation setPreviewCallbackAllocation} to use
* the created Allocation as a destination for camera preview frames. The Allocation will be created with a YUV type, and its contents must
* be accessed within Renderscript with the {@code rsGetElementAtYuv_*}
* accessor methods. Its size will be based on the current
* {@link Parameters#getPreviewSize preview size} configured for this
* camera. Set an {@link android.renderscript.Allocation Allocation} as the
* target of preview callback data. Use this method for efficient processing
* of camera preview data with RenderScript. The Allocation must be created
* with the {@link #createPreviewAllocation createPreviewAllocation }
* method. Setting a preview allocation will disable any active preview callbacks
* set by {@link #setPreviewCallback setPreviewCallback} or
* {@link #setPreviewCallbackWithBuffer setPreviewCallbackWithBuffer}, and
* vice versa. Using a preview allocation still requires an active standard
* preview target to be set, either with
* {@link #setPreviewTexture setPreviewTexture} or
* {@link #setPreviewDisplay setPreviewDisplay}. To be notified when new frames are available to the Allocation, use
* {@link android.renderscript.Allocation#setIoInputNotificationHandler Allocation.setIoInputNotificationHandler}. To
* update the frame currently accessible from the Allocation to the latest
* preview frame, call
* {@link android.renderscript.Allocation#ioReceive Allocation.ioReceive}. To disable preview into the Allocation, call this method with a
* {@code null} parameter. Once a preview allocation is set, the preview size set by
* {@link Parameters#setPreviewSize setPreviewSize} cannot be changed. If
* you wish to change the preview size, first remove the preview allocation
* by calling {@code setPreviewCallbackAllocation(null)}, then change the
* preview size, create a new preview Allocation with
* {@link #createPreviewAllocation createPreviewAllocation}, and set it as
* the new preview callback allocation target. If you are using the preview data to create video or still images,
* strongly consider using {@link android.media.MediaActionSound} to
* properly indicate image capture or recording start/stop to the user. 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 without auto-focus, you must
* declare that your app uses the
* {@code android.hardware.camera.autofocus} feature, in the
* <uses-feature>
* manifest element. 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.
*
* If your application should not be installed
* on devices without auto-focus, you must declare that your application
* uses auto-focus with the
* <uses-feature>
* manifest element. 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 and camera hardware.
*
* Auto-exposure lock {@link android.hardware.Camera.Parameters#getAutoExposureLock()}
* and auto-white balance locks {@link android.hardware.Camera.Parameters#getAutoWhiteBalanceLock()}
* do not change during and after autofocus. But auto-focus routine may stop
* auto-exposure and auto-white balance transiently during focusing.
*
* Stopping preview with {@link #stopPreview()}, or triggering still
* image capture with {@link #takePicture(Camera.ShutterCallback,
* Camera.PictureCallback, Camera.PictureCallback)}, will not change the
* the focus position. Applications must call cancelAutoFocus to reset the
* focus. If autofocus is successful, consider using
* {@link android.media.MediaActionSound} to properly play back an autofocus
* success sound to the user. This is only supported in continuous autofocus modes -- {@link
* Parameters#FOCUS_MODE_CONTINUOUS_VIDEO} and {@link
* Parameters#FOCUS_MODE_CONTINUOUS_PICTURE}. Applications can show
* autofocus animation based on this. 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. This should not be called between
* {@link android.media.MediaRecorder#start()} and
* {@link android.media.MediaRecorder#stop()}.
*
* 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 the callback for JPEG image data, or null
*/
public final void takePicture(ShutterCallback shutter, PictureCallback raw,
PictureCallback postview, PictureCallback jpeg) {
mShutterCallback = shutter;
mRawImageCallback = raw;
mPostviewCallback = postview;
mJpegCallback = jpeg;
// If callback is not set, do not send me callbacks.
int msgType = 0;
if (mShutterCallback != null) {
msgType |= CAMERA_MSG_SHUTTER;
}
if (mRawImageCallback != null) {
msgType |= CAMERA_MSG_RAW_IMAGE;
}
if (mPostviewCallback != null) {
msgType |= CAMERA_MSG_POSTVIEW_FRAME;
}
if (mJpegCallback != null) {
msgType |= CAMERA_MSG_COMPRESSED_IMAGE;
}
native_takePicture(msgType);
mFaceDetectionRunning = false;
}
/**
* 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. 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. 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.
*
* @throws RuntimeException if the method fails.
*/
public native final void stopSmoothZoom();
/**
* Set the clockwise rotation of preview display in degrees. This affects
* the preview frames and the picture displayed after snapshot. This method
* is useful for portrait mode applications. Note that preview display of
* front-facing cameras is flipped horizontally before the rotation, that
* is, the image is reflected along the central vertical axis of the camera
* sensor. So the users can see themselves as looking into a mirror.
*
* This does not affect the order of byte array passed in {@link
* PreviewCallback#onPreviewFrame}, JPEG pictures, or recorded videos. This
* method is not allowed to be called during preview.
*
* If you want to make the camera image show in the same orientation as
* the display, you can use the following code.
* Starting from API level 14, this method can be called when preview is
* active.
*
* Note: Before API level 24, the default value for orientation is 0. Starting in
* API level 24, the default orientation will be such that applications in forced-landscape mode
* will have correct preview orientation, which may be either a default of 0 or
* 180. Applications that operate in portrait mode or allow for changing orientation must still
* call this method after each orientation change to ensure correct preview display in all
* cases. Enable or disable the default shutter sound when taking a picture. By default, the camera plays the system-defined camera shutter sound
* when {@link #takePicture} is called. Using this method, the shutter sound
* can be disabled. It is strongly recommended that an alternative shutter
* sound is played in the {@link ShutterCallback} when the system shutter
* sound is disabled. Note that devices may not always allow disabling the camera shutter
* sound. If the shutter sound state cannot be set to the desired value,
* this method will return false. {@link CameraInfo#canDisableShutterSound}
* can be used to determine whether the device will allow the shutter sound
* to be disabled.
* This is only guaranteed to work for legacy cameras
* (i.e. initialized with {@link #cameraInitUnspecified}). Trying to call this on
* a regular camera will force a conditional check in the camera service.
* When the face detection is running, {@link Parameters#setWhiteBalance(String)},
* {@link Parameters#setFocusAreas(List)}, and {@link Parameters#setMeteringAreas(List)}
* have no effect. The camera uses the detected faces to do auto-white balance,
* auto exposure, and autofocus.
*
* If the apps call {@link #autoFocus(AutoFocusCallback)}, the camera
* will stop sending face callbacks. The last face callback indicates the
* areas used to do autofocus. After focus completes, face detection will
* resume sending face callbacks. If the apps call {@link
* #cancelAutoFocus()}, the face callbacks will also resume. After calling {@link #takePicture(Camera.ShutterCallback, Camera.PictureCallback,
* Camera.PictureCallback)} or {@link #stopPreview()}, and then resuming
* preview with {@link #startPreview()}, the apps should call this method
* again to resume face detection. When face detection is used with a camera, the {@link FaceDetectionListener} returns a
* list of face objects for use in focusing and metering. The direction is relative to the sensor orientation, that is, what
* the sensor sees. The direction is not affected by the rotation or
* mirroring of {@link #setDisplayOrientation(int)}. The face bounding
* rectangle does not provide any information about face orientation. Here is the matrix to convert driver coordinates to View coordinates
* in pixels. The confidence level for the detection of the face. The range is 1 to
* 100. 100 is the highest confidence. Depending on the device, even very low-confidence faces may be
* listed, so applications should filter out faces with low confidence,
* depending on the use case. For a typical point-and-shoot camera
* application that wishes to display rectangles around detected faces,
* filtering out faces with confidence less than 50 is recommended. The Area class is used for choosing specific metering and focus areas for
* the camera to use when calculating auto-exposure, auto-white balance, and
* auto-focus. To find out how many simultaneous areas a given camera supports, use
* {@link Parameters#getMaxNumMeteringAreas()} and
* {@link Parameters#getMaxNumFocusAreas()}. If metering or focusing area
* selection is unsupported, these methods will return 0. Each Area consists of a rectangle specifying its bounds, and a weight
* that determines its importance. The bounds are relative to the camera's
* current field of view. The coordinates are mapped so that (-1000, -1000)
* is always the top-left corner of the current field of view, and (1000,
* 1000) is always the bottom-right corner of the current field of
* view. Setting Areas with bounds outside that range is not allowed. Areas
* with zero or negative width or height are not allowed. The weight must range from 1 to 1000, and represents a weight for
* every pixel in the area. This means that a large metering area with
* the same weight as a smaller area will have more effect in the
* metering result. Metering areas can overlap and the driver
* will add the weights in the overlap region. To make camera parameters take effect, applications have to call
* {@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.
*
* 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 {@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.
*
* @deprecated We recommend using the new {@link android.hardware.camera2} API for new
* applications.
*/
@Deprecated
public class Parameters {
// Parameter keys to communicate with the camera driver.
private static final String KEY_PREVIEW_SIZE = "preview-size";
private static final String KEY_PREVIEW_FORMAT = "preview-format";
private static final String KEY_PREVIEW_FRAME_RATE = "preview-frame-rate";
private static final String KEY_PREVIEW_FPS_RANGE = "preview-fps-range";
private static final String KEY_PICTURE_SIZE = "picture-size";
private static final String KEY_PICTURE_FORMAT = "picture-format";
private static final String KEY_JPEG_THUMBNAIL_SIZE = "jpeg-thumbnail-size";
private static final String KEY_JPEG_THUMBNAIL_WIDTH = "jpeg-thumbnail-width";
private static final String KEY_JPEG_THUMBNAIL_HEIGHT = "jpeg-thumbnail-height";
private static final String KEY_JPEG_THUMBNAIL_QUALITY = "jpeg-thumbnail-quality";
private static final String KEY_JPEG_QUALITY = "jpeg-quality";
private static final String KEY_ROTATION = "rotation";
private static final String KEY_GPS_LATITUDE = "gps-latitude";
private static final String KEY_GPS_LONGITUDE = "gps-longitude";
private static final String KEY_GPS_ALTITUDE = "gps-altitude";
private static final String KEY_GPS_TIMESTAMP = "gps-timestamp";
private static final String KEY_GPS_PROCESSING_METHOD = "gps-processing-method";
private static final String KEY_WHITE_BALANCE = "whitebalance";
private static final String KEY_EFFECT = "effect";
private static final String KEY_ANTIBANDING = "antibanding";
private static final String KEY_SCENE_MODE = "scene-mode";
private static final String KEY_FLASH_MODE = "flash-mode";
private static final String KEY_FOCUS_MODE = "focus-mode";
private static final String KEY_FOCUS_AREAS = "focus-areas";
private static final String KEY_MAX_NUM_FOCUS_AREAS = "max-num-focus-areas";
private static final String KEY_FOCAL_LENGTH = "focal-length";
private static final String KEY_HORIZONTAL_VIEW_ANGLE = "horizontal-view-angle";
private static final String KEY_VERTICAL_VIEW_ANGLE = "vertical-view-angle";
private static final String KEY_EXPOSURE_COMPENSATION = "exposure-compensation";
private static final String KEY_MAX_EXPOSURE_COMPENSATION = "max-exposure-compensation";
private static final String KEY_MIN_EXPOSURE_COMPENSATION = "min-exposure-compensation";
private static final String KEY_EXPOSURE_COMPENSATION_STEP = "exposure-compensation-step";
private static final String KEY_AUTO_EXPOSURE_LOCK = "auto-exposure-lock";
private static final String KEY_AUTO_EXPOSURE_LOCK_SUPPORTED = "auto-exposure-lock-supported";
private static final String KEY_AUTO_WHITEBALANCE_LOCK = "auto-whitebalance-lock";
private static final String KEY_AUTO_WHITEBALANCE_LOCK_SUPPORTED = "auto-whitebalance-lock-supported";
private static final String KEY_METERING_AREAS = "metering-areas";
private static final String KEY_MAX_NUM_METERING_AREAS = "max-num-metering-areas";
private static final String KEY_ZOOM = "zoom";
private static final String KEY_MAX_ZOOM = "max-zoom";
private static final String KEY_ZOOM_RATIOS = "zoom-ratios";
private static final String KEY_ZOOM_SUPPORTED = "zoom-supported";
private static final String KEY_SMOOTH_ZOOM_SUPPORTED = "smooth-zoom-supported";
private static final String KEY_FOCUS_DISTANCES = "focus-distances";
private static final String KEY_VIDEO_SIZE = "video-size";
private static final String KEY_PREFERRED_PREVIEW_SIZE_FOR_VIDEO =
"preferred-preview-size-for-video";
private static final String KEY_MAX_NUM_DETECTED_FACES_HW = "max-num-detected-faces-hw";
private static final String KEY_MAX_NUM_DETECTED_FACES_SW = "max-num-detected-faces-sw";
private static final String KEY_RECORDING_HINT = "recording-hint";
private static final String KEY_VIDEO_SNAPSHOT_SUPPORTED = "video-snapshot-supported";
private static final String KEY_VIDEO_STABILIZATION = "video-stabilization";
private static final String KEY_VIDEO_STABILIZATION_SUPPORTED = "video-stabilization-supported";
// Parameter key suffix for supported values.
private static final String SUPPORTED_VALUES_SUFFIX = "-values";
private static final String TRUE = "true";
private static final String FALSE = "false";
// Values for white balance settings.
public static final String WHITE_BALANCE_AUTO = "auto";
public static final String WHITE_BALANCE_INCANDESCENT = "incandescent";
public static final String WHITE_BALANCE_FLUORESCENT = "fluorescent";
public static final String WHITE_BALANCE_WARM_FLUORESCENT = "warm-fluorescent";
public static final String WHITE_BALANCE_DAYLIGHT = "daylight";
public static final String WHITE_BALANCE_CLOUDY_DAYLIGHT = "cloudy-daylight";
public static final String WHITE_BALANCE_TWILIGHT = "twilight";
public static final String WHITE_BALANCE_SHADE = "shade";
// Values for color effect settings.
public static final String EFFECT_NONE = "none";
public static final String EFFECT_MONO = "mono";
public static final String EFFECT_NEGATIVE = "negative";
public static final String EFFECT_SOLARIZE = "solarize";
public static final String EFFECT_SEPIA = "sepia";
public static final String EFFECT_POSTERIZE = "posterize";
public static final String EFFECT_WHITEBOARD = "whiteboard";
public static final String EFFECT_BLACKBOARD = "blackboard";
public static final String EFFECT_AQUA = "aqua";
// Values for antibanding settings.
public static final String ANTIBANDING_AUTO = "auto";
public static final String ANTIBANDING_50HZ = "50hz";
public static final String ANTIBANDING_60HZ = "60hz";
public static final String ANTIBANDING_OFF = "off";
// Values for flash mode settings.
/**
* Flash will not be fired.
*/
public static final String FLASH_MODE_OFF = "off";
/**
* Flash will be fired automatically when required. The flash may be fired
* during preview, auto-focus, or snapshot depending on the driver.
*/
public static final String FLASH_MODE_AUTO = "auto";
/**
* Flash will always be fired during snapshot. The flash may also be
* fired during preview or auto-focus depending on the driver.
*/
public static final String FLASH_MODE_ON = "on";
/**
* Flash will be fired in red-eye reduction mode.
*/
public static final String FLASH_MODE_RED_EYE = "red-eye";
/**
* Constant emission of light during preview, auto-focus and snapshot.
* This can also be used for video recording.
*/
public static final String FLASH_MODE_TORCH = "torch";
/**
* Scene mode is off.
*/
public static final String SCENE_MODE_AUTO = "auto";
/**
* Take photos of fast moving objects. Same as {@link
* #SCENE_MODE_SPORTS}.
*/
public static final String SCENE_MODE_ACTION = "action";
/**
* Take people pictures.
*/
public static final String SCENE_MODE_PORTRAIT = "portrait";
/**
* Take pictures on distant objects.
*/
public static final String SCENE_MODE_LANDSCAPE = "landscape";
/**
* Take photos at night.
*/
public static final String SCENE_MODE_NIGHT = "night";
/**
* Take people pictures at night.
*/
public static final String SCENE_MODE_NIGHT_PORTRAIT = "night-portrait";
/**
* Take photos in a theater. Flash light is off.
*/
public static final String SCENE_MODE_THEATRE = "theatre";
/**
* Take pictures on the beach.
*/
public static final String SCENE_MODE_BEACH = "beach";
/**
* Take pictures on the snow.
*/
public static final String SCENE_MODE_SNOW = "snow";
/**
* Take sunset photos.
*/
public static final String SCENE_MODE_SUNSET = "sunset";
/**
* Avoid blurry pictures (for example, due to hand shake).
*/
public static final String SCENE_MODE_STEADYPHOTO = "steadyphoto";
/**
* For shooting firework displays.
*/
public static final String SCENE_MODE_FIREWORKS = "fireworks";
/**
* Take photos of fast moving objects. Same as {@link
* #SCENE_MODE_ACTION}.
*/
public static final String SCENE_MODE_SPORTS = "sports";
/**
* Take indoor low-light shot.
*/
public static final String SCENE_MODE_PARTY = "party";
/**
* Capture the naturally warm color of scenes lit by candles.
*/
public static final String SCENE_MODE_CANDLELIGHT = "candlelight";
/**
* Applications are looking for a barcode. Camera driver will be
* optimized for barcode reading.
*/
public static final String SCENE_MODE_BARCODE = "barcode";
/**
* Capture a scene using high dynamic range imaging techniques. The
* camera will return an image that has an extended dynamic range
* compared to a regular capture. Capturing such an image may take
* longer than a regular capture.
*/
public static final String SCENE_MODE_HDR = "hdr";
/**
* Auto-focus mode. Applications should call {@link
* #autoFocus(AutoFocusCallback)} to start the focus in this mode.
*/
public static final String FOCUS_MODE_AUTO = "auto";
/**
* Focus is set at infinity. Applications should not call
* {@link #autoFocus(AutoFocusCallback)} in this mode.
*/
public static final String FOCUS_MODE_INFINITY = "infinity";
/**
* Macro (close-up) focus mode. Applications should call
* {@link #autoFocus(AutoFocusCallback)} to start the focus in this
* mode.
*/
public static final String FOCUS_MODE_MACRO = "macro";
/**
* Focus is fixed. The camera is always in this mode if the focus is not
* adjustable. If the camera has auto-focus, this mode can fix the
* focus, which is usually at hyperfocal distance. Applications should
* not call {@link #autoFocus(AutoFocusCallback)} in this mode.
*/
public static final String FOCUS_MODE_FIXED = "fixed";
/**
* Extended depth of field (EDOF). Focusing is done digitally and
* continuously. Applications should not call {@link
* #autoFocus(AutoFocusCallback)} in this mode.
*/
public static final String FOCUS_MODE_EDOF = "edof";
/**
* Continuous auto focus mode intended for video recording. The camera
* continuously tries to focus. This is the best choice for video
* recording because the focus changes smoothly . Applications still can
* call {@link #takePicture(Camera.ShutterCallback,
* Camera.PictureCallback, Camera.PictureCallback)} in this mode but the
* subject may not be in focus. Auto focus starts when the parameter is
* set.
*
* Since API level 14, applications can call {@link
* #autoFocus(AutoFocusCallback)} in this mode. The focus callback will
* immediately return with a boolean that indicates whether the focus is
* sharp or not. The focus position is locked after autoFocus call. If
* applications want to resume the continuous focus, cancelAutoFocus
* must be called. Restarting the preview will not resume the continuous
* autofocus. To stop continuous focus, applications should change the
* focus mode to other modes.
*
* @see #FOCUS_MODE_CONTINUOUS_PICTURE
*/
public static final String FOCUS_MODE_CONTINUOUS_VIDEO = "continuous-video";
/**
* Continuous auto focus mode intended for taking pictures. The camera
* continuously tries to focus. The speed of focus change is more
* aggressive than {@link #FOCUS_MODE_CONTINUOUS_VIDEO}. Auto focus
* starts when the parameter is set.
*
* Applications can call {@link #autoFocus(AutoFocusCallback)} in
* this mode. If the autofocus is in the middle of scanning, the focus
* callback will return when it completes. If the autofocus is not
* scanning, the focus callback will immediately return with a boolean
* that indicates whether the focus is sharp or not. The apps can then
* decide if they want to take a picture immediately or to change the
* focus mode to auto, and run a full autofocus cycle. The focus
* position is locked after autoFocus call. If applications want to
* resume the continuous focus, cancelAutoFocus must be called.
* Restarting the preview will not resume the continuous autofocus. To
* stop continuous focus, applications should change the focus mode to
* other modes.
*
* @see #FOCUS_MODE_CONTINUOUS_VIDEO
*/
public static final String FOCUS_MODE_CONTINUOUS_PICTURE = "continuous-picture";
// Indices for focus distance array.
/**
* The array index of near focus distance for use with
* {@link #getFocusDistances(float[])}.
*/
public static final int FOCUS_DISTANCE_NEAR_INDEX = 0;
/**
* The array index of optimal focus distance for use with
* {@link #getFocusDistances(float[])}.
*/
public static final int FOCUS_DISTANCE_OPTIMAL_INDEX = 1;
/**
* The array index of far focus distance for use with
* {@link #getFocusDistances(float[])}.
*/
public static final int FOCUS_DISTANCE_FAR_INDEX = 2;
/**
* The array index of minimum preview fps for use with {@link
* #getPreviewFpsRange(int[])} or {@link
* #getSupportedPreviewFpsRange()}.
*/
public static final int PREVIEW_FPS_MIN_INDEX = 0;
/**
* The array index of maximum preview fps for use with {@link
* #getPreviewFpsRange(int[])} or {@link
* #getSupportedPreviewFpsRange()}.
*/
public static final int PREVIEW_FPS_MAX_INDEX = 1;
// Formats for setPreviewFormat and setPictureFormat.
private static final String PIXEL_FORMAT_YUV422SP = "yuv422sp";
private static final String PIXEL_FORMAT_YUV420SP = "yuv420sp";
private static final String PIXEL_FORMAT_YUV422I = "yuv422i-yuyv";
private static final String PIXEL_FORMAT_YUV420P = "yuv420p";
private static final String PIXEL_FORMAT_RGB565 = "rgb565";
private static final String PIXEL_FORMAT_JPEG = "jpeg";
private static final String PIXEL_FORMAT_BAYER_RGGB = "bayer-rggb";
/**
* Order matters: Keys that are {@link #set(String, String) set} later
* will take precedence over keys that are set earlier (if the two keys
* conflict with each other).
*
* One example is {@link #setPreviewFpsRange(int, int)} , since it
* conflicts with {@link #setPreviewFrameRate(int)} whichever key is set later
* is the one that will take precedence.
* The {@link #unflatten(String)} method does the reverse. The {@link #flatten()} method does the reverse. Gets the supported video frame sizes that can be used by
* MediaRecorder. If the returned list is not null, the returned list will contain at
* least one Size and one of the sizes in the returned list must be
* passed to MediaRecorder.setVideoSize() for camcorder application if
* camera is used as the video source. In this case, the size of the
* preview can be different from the resolution of the recorded video
* during video recording. Sets the dimensions for EXIF thumbnail in Jpeg picture. If
* applications set both width and height to 0, EXIF will not contain
* thumbnail. Applications need to consider the display orientation. See {@link
* #setPreviewSize(int,int)} for reference. If this is never called, the default format will be
* {@link android.graphics.ImageFormat#NV21}, which
* uses the NV21 encoding format. Use {@link Parameters#getSupportedPreviewFormats} to get a list of
* the available preview formats.
*
* It is strongly recommended that either
* {@link android.graphics.ImageFormat#NV21} or
* {@link android.graphics.ImageFormat#YV12} is used, since
* they are supported by all camera devices. For YV12, the image buffer that is received is not necessarily
* tightly packed, as there may be padding at the end of each row of
* pixel data, as described in
* {@link android.graphics.ImageFormat#YV12}. For camera callback data,
* it can be assumed that the stride of the Y and UV data is the
* smallest possible that meets the alignment requirements. That is, if
* the preview size is width x height, then the following
* equations describe the buffer index for the beginning of row
* y for the Y plane and row c for the U and V
* planes:
*
* Sets the dimensions for pictures. Applications need to consider the display orientation. See {@link
* #setPreviewSize(int,int)} for reference.
* If applications want to rotate the picture to match the orientation
* of what users see, apps should use
* {@link android.view.OrientationEventListener} and
* {@link android.hardware.Camera.CameraInfo}. The value from
* OrientationEventListener is relative to the natural orientation of
* the device. CameraInfo.orientation is the angle between camera
* orientation and natural device orientation. The sum of the two is the
* rotation angle for back-facing camera. The difference of the two is
* the rotation angle for front-facing camera. Note that the JPEG
* pictures of front-facing cameras are not mirrored as in preview
* display.
*
*
* For example, suppose the natural orientation of the device is
* portrait. The device is rotated 270 degrees clockwise, so the device
* orientation is 270. Suppose a back-facing camera sensor is mounted in
* landscape and the top side of the camera sensor is aligned with the
* right edge of the display in natural orientation. So the camera
* orientation is 90. The rotation should be set to 0 (270 + 90).
*
* The reference code is as follows.
*
* Sets the auto-exposure lock state. Applications should check
* {@link #isAutoExposureLockSupported} before using this method. If set to true, the camera auto-exposure routine will immediately
* pause until the lock is set to false. Exposure compensation settings
* changes will still take effect while auto-exposure is locked. If auto-exposure is already locked, setting this to true again has
* no effect (the driver will not recalculate exposure values). Stopping preview with {@link #stopPreview()}, or triggering still
* image capture with {@link #takePicture(Camera.ShutterCallback,
* Camera.PictureCallback, Camera.PictureCallback)}, will not change the
* lock. Exposure compensation, auto-exposure lock, and auto-white balance
* lock can be used to capture an exposure-bracketed burst of images,
* for example. Auto-exposure state, including the lock state, will not be
* maintained after camera {@link #release()} is called. Locking
* auto-exposure after {@link #open()} but before the first call to
* {@link #startPreview()} will not allow the auto-exposure routine to
* run at all, and may result in severely over- or under-exposed
* images. Sets the auto-white balance lock state. Applications should check
* {@link #isAutoWhiteBalanceLockSupported} before using this
* method. If set to true, the camera auto-white balance routine will
* immediately pause until the lock is set to false. If auto-white balance is already locked, setting this to true
* again has no effect (the driver will not recalculate white balance
* values). Stopping preview with {@link #stopPreview()}, or triggering still
* image capture with {@link #takePicture(Camera.ShutterCallback,
* Camera.PictureCallback, Camera.PictureCallback)}, will not change the
* the lock. Changing the white balance mode with {@link #setWhiteBalance}
* will release the auto-white balance lock if it is set. Exposure compensation, AE lock, and AWB lock can be used to
* capture an exposure-bracketed burst of images, for example.
* Auto-white balance state, including the lock state, will not be
* maintained after camera {@link #release()} is called. Locking
* auto-white balance after {@link #open()} but before the first call to
* {@link #startPreview()} will not allow the auto-white balance routine
* to run at all, and may result in severely incorrect color in captured
* images. Gets the distances from the camera to where an object appears to be
* in focus. The object is sharpest at the optimal focus distance. The
* depth of field is the far focus distance minus near focus distance. Focus distances may change after calling {@link
* #autoFocus(AutoFocusCallback)}, {@link #cancelAutoFocus}, or {@link
* #startPreview()}. Applications can call {@link #getParameters()}
* and this method anytime to get the latest focus distances. If the
* focus mode is FOCUS_MODE_CONTINUOUS_VIDEO, focus distances may change
* from time to time. This method is intended to estimate the distance between the camera
* and the subject. After autofocus, the subject distance may be within
* near and far focus distance. However, the precision depends on the
* camera hardware, autofocus algorithm, the focus area, and the scene.
* The error can be large and it should be only used as a reference. Far focus distance >= optimal focus distance >= near focus distance.
* If the focus distance is infinity, the value will be
* {@code Float.POSITIVE_INFINITY}. Gets the current focus areas. Camera driver uses the areas to decide
* focus. Before using this API or {@link #setFocusAreas(List)}, apps should
* call {@link #getMaxNumFocusAreas()} to know the maximum number of
* focus areas first. If the value is 0, focus area is not supported. Each focus area is a rectangle with specified weight. The direction
* is relative to the sensor orientation, that is, what the sensor sees.
* The direction is not affected by the rotation or mirroring of
* {@link #setDisplayOrientation(int)}. Coordinates of the rectangle
* range from -1000 to 1000. (-1000, -1000) is the upper left point.
* (1000, 1000) is the lower right point. The width and height of focus
* areas cannot be 0 or negative. The weight must range from 1 to 1000. The weight should be
* interpreted as a per-pixel weight - all pixels in the area have the
* specified weight. This means a small area with the same weight as a
* larger area will have less influence on the focusing than the larger
* area. Focus areas can partially overlap and the driver will add the
* weights in the overlap region. A special case of a {@code null} focus area list means the driver is
* free to select focus targets as it wants. For example, the driver may
* use more signals to select focus areas and change them
* dynamically. Apps can set the focus area list to {@code null} if they
* want the driver to completely control focusing. Focus areas are relative to the current field of view
* ({@link #getZoom()}). No matter what the zoom level is, (-1000,-1000)
* represents the top of the currently visible camera frame. The focus
* area cannot be set to be outside the current field of view, even
* when using zoom. Focus area only has effect if the current focus mode is
* {@link #FOCUS_MODE_AUTO}, {@link #FOCUS_MODE_MACRO},
* {@link #FOCUS_MODE_CONTINUOUS_VIDEO}, or
* {@link #FOCUS_MODE_CONTINUOUS_PICTURE}. Gets the current metering areas. Camera driver uses these areas to
* decide exposure. Before using this API or {@link #setMeteringAreas(List)}, apps should
* call {@link #getMaxNumMeteringAreas()} to know the maximum number of
* metering areas first. If the value is 0, metering area is not
* supported. Each metering area is a rectangle with specified weight. The
* direction is relative to the sensor orientation, that is, what the
* sensor sees. The direction is not affected by the rotation or
* mirroring of {@link #setDisplayOrientation(int)}. Coordinates of the
* rectangle range from -1000 to 1000. (-1000, -1000) is the upper left
* point. (1000, 1000) is the lower right point. The width and height of
* metering areas cannot be 0 or negative. The weight must range from 1 to 1000, and represents a weight for
* every pixel in the area. This means that a large metering area with
* the same weight as a smaller area will have more effect in the
* metering result. Metering areas can partially overlap and the driver
* will add the weights in the overlap region. A special case of a {@code null} metering area list means the driver
* is free to meter as it chooses. For example, the driver may use more
* signals to select metering areas and change them dynamically. Apps
* can set the metering area list to {@code null} if they want the
* driver to completely control metering. Metering areas are relative to the current field of view
* ({@link #getZoom()}). No matter what the zoom level is, (-1000,-1000)
* represents the top of the currently visible camera frame. The
* metering area cannot be set to be outside the current field of view,
* even when using zoom. No matter what metering areas are, the final exposure are compensated
* by {@link #setExposureCompensation(int)}. Returns true if video snapshot is supported. That is, applications
* can call {@link #takePicture(Camera.ShutterCallback,
* Camera.PictureCallback, Camera.PictureCallback,
* Camera.PictureCallback)} during recording. Applications do not need
* to call {@link #startPreview()} after taking a picture. The preview
* will be still active. Other than that, taking a picture during
* recording is identical to taking a picture normally. All settings and
* methods related to takePicture work identically. Ex:
* {@link #getPictureSize()}, {@link #getSupportedPictureSizes()},
* {@link #setJpegQuality(int)}, {@link #setRotation(int)}, and etc. The
* picture will have an EXIF header. {@link #FLASH_MODE_AUTO} and
* {@link #FLASH_MODE_ON} also still work, but the video will record the
* flash. Applications can set shutter callback as null to avoid the shutter
* sound. It is also recommended to set raw picture and post view
* callbacks to null to avoid the interrupt of preview display. Field-of-view of the recorded video may be different from that of the
* captured pictures. The maximum size of a video snapshot may be
* smaller than that for regular still captures. If the current picture
* size is set higher than can be supported by video snapshot, the
* picture will be captured at the maximum supported size instead. Enables and disables video stabilization. Use
* {@link #isVideoStabilizationSupported} to determine if calling this
* method is valid. Video stabilization reduces the shaking due to the motion of the
* camera in both the preview stream and in recorded videos, including
* data received from the preview callback. It does not reduce motion
* blur in images captured with
* {@link Camera#takePicture takePicture}. Video stabilization can be enabled and disabled while preview or
* recording is active, but toggling it may cause a jump in the video
* stream that may be undesirable in a recorded video.success set to true.
*
* The auto-focus routine does not lock auto-exposure and auto-white
* balance after it completes.
*
* @param success true if focus was successful, false if otherwise
* @param camera the Camera service object
* @see android.hardware.Camera.Parameters#setAutoExposureLock(boolean)
* @see android.hardware.Camera.Parameters#setAutoWhiteBalanceLock(boolean)
*/
void onAutoFocus(boolean success, Camera 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()}).
*
*
* public static void setCameraDisplayOrientation(Activity activity,
* int cameraId, android.hardware.Camera camera) {
* android.hardware.Camera.CameraInfo info =
* new android.hardware.Camera.CameraInfo();
* android.hardware.Camera.getCameraInfo(cameraId, info);
* int rotation = activity.getWindowManager().getDefaultDisplay()
* .getRotation();
* int degrees = 0;
* switch (rotation) {
* case Surface.ROTATION_0: degrees = 0; break;
* case Surface.ROTATION_90: degrees = 90; break;
* case Surface.ROTATION_180: degrees = 180; break;
* case Surface.ROTATION_270: degrees = 270; break;
* }
*
* int result;
* if (info.facing == Camera.CameraInfo.CAMERA_FACING_FRONT) {
* result = (info.orientation + degrees) % 360;
* result = (360 - result) % 360; // compensate the mirror
* } else { // back-facing
* result = (info.orientation - degrees + 360) % 360;
* }
* camera.setDisplayOrientation(result);
* }
*
*
*
* Matrix matrix = new Matrix();
* CameraInfo info = CameraHolder.instance().getCameraInfo()[cameraId];
* // Need mirror for front camera.
* boolean mirror = (info.facing == CameraInfo.CAMERA_FACING_FRONT);
* matrix.setScale(mirror ? -1 : 1, 1);
* // This is the value for android.hardware.Camera.setDisplayOrientation.
* matrix.postRotate(displayOrientation);
* // Camera driver coordinates range from (-1000, -1000) to (1000, 1000).
* // UI coordinates range from (0, 0) to (width, height).
* matrix.postScale(view.getWidth() / 2000f, view.getHeight() / 2000f);
* matrix.postTranslate(view.getWidth() / 2f, view.getHeight() / 2f);
*
*
* @see #startFaceDetection()
*/
public Rect rect;
/**
*
*
* @param camera the Camera service object
*/
void onError(int error, Camera camera);
};
/**
* Registers a callback to be invoked when an error occurs.
* @param cb The callback to run
*/
public final void setErrorCallback(ErrorCallback cb)
{
mErrorCallback = cb;
}
private native final void native_setParameters(String params);
private native final String native_getParameters();
/**
* Changes the settings for this Camera service.
*
* @param params the Parameters to use for this Camera service
* @throws RuntimeException if any parameter is invalid or not supported.
* @see #getParameters()
*/
public void setParameters(Parameters params) {
// If using preview allocations, don't allow preview size changes
if (mUsingPreviewAllocation) {
Size newPreviewSize = params.getPreviewSize();
Size currentPreviewSize = getParameters().getPreviewSize();
if (newPreviewSize.width != currentPreviewSize.width ||
newPreviewSize.height != currentPreviewSize.height) {
throw new IllegalStateException("Cannot change preview size" +
" while a preview allocation is configured.");
}
}
native_setParameters(params.flatten());
}
/**
* 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();
String s = native_getParameters();
p.unflatten(s);
return p;
}
/**
* Returns an empty {@link Parameters} for testing purpose.
*
* @return a Parameter object.
*
* @hide
*/
public static Parameters getEmptyParameters() {
Camera camera = new Camera();
return camera.new Parameters();
}
/**
* Returns a copied {@link Parameters}; for shim use only.
*
* @param parameters a non-{@code null} parameters
* @return a Parameter object, with all the parameters copied from {@code parameters}.
*
* @throws NullPointerException if {@code parameters} was {@code null}
* @hide
*/
public static Parameters getParametersCopy(Camera.Parameters parameters) {
if (parameters == null) {
throw new NullPointerException("parameters must not be null");
}
Camera camera = parameters.getOuter();
Parameters p = camera.new Parameters();
p.copyFrom(parameters);
return p;
}
/**
* Image size (width and height dimensions).
* @deprecated We recommend using the new {@link android.hardware.camera2} API for new
* applications.
*/
@Deprecated
public class Size {
/**
* Sets the dimensions for pictures.
*
* @param w the photo width (pixels)
* @param h the photo height (pixels)
*/
public Size(int w, int h) {
width = w;
height = h;
}
/**
* Compares {@code obj} to this size.
*
* @param obj the object to compare this size with.
* @return {@code true} if the width and height of {@code obj} is the
* same as those of this size. {@code false} otherwise.
*/
@Override
public boolean equals(Object obj) {
if (!(obj instanceof Size)) {
return false;
}
Size s = (Size) obj;
return width == s.width && height == s.height;
}
@Override
public int hashCode() {
return width * 32713 + height;
}
/** width of the picture */
public int width;
/** height of the picture */
public int height;
};
/**
* {@code
* yStride = (int) ceil(width / 16.0) * 16;
* uvStride = (int) ceil( (yStride / 2) / 16.0) * 16;
* ySize = yStride * height;
* uvSize = uvStride * height / 2;
* yRowIndex = yStride * y;
* uRowIndex = ySize + uvSize + uvStride * c;
* vRowIndex = ySize + uvStride * c;
* size = ySize + uvSize * 2;
* }
*
*
* @param pixel_format the desired preview picture format, defined by
* one of the {@link android.graphics.ImageFormat} constants. (E.g.,
* ImageFormat.NV21 (default), or
* ImageFormat.YV12)
*
* @see android.graphics.ImageFormat
* @see android.hardware.Camera.Parameters#getSupportedPreviewFormats
*/
public void setPreviewFormat(int pixel_format) {
String s = cameraFormatForPixelFormat(pixel_format);
if (s == null) {
throw new IllegalArgumentException(
"Invalid pixel_format=" + pixel_format);
}
set(KEY_PREVIEW_FORMAT, s);
}
/**
* Returns the image format for preview frames got from
* {@link PreviewCallback}.
*
* @return the preview format.
* @see android.graphics.ImageFormat
* @see #setPreviewFormat
*/
public int getPreviewFormat() {
return pixelFormatForCameraFormat(get(KEY_PREVIEW_FORMAT));
}
/**
* Gets the supported preview formats. {@link android.graphics.ImageFormat#NV21}
* is always supported. {@link android.graphics.ImageFormat#YV12}
* is always supported since API level 12.
*
* @return a list of supported preview formats. This method will always
* return a list with at least one element.
* @see android.graphics.ImageFormat
* @see #setPreviewFormat
*/
public List
* public void onOrientationChanged(int orientation) {
* if (orientation == ORIENTATION_UNKNOWN) return;
* android.hardware.Camera.CameraInfo info =
* new android.hardware.Camera.CameraInfo();
* android.hardware.Camera.getCameraInfo(cameraId, info);
* orientation = (orientation + 45) / 90 * 90;
* int rotation = 0;
* if (info.facing == CameraInfo.CAMERA_FACING_FRONT) {
* rotation = (info.orientation - orientation + 360) % 360;
* } else { // back-facing camera
* rotation = (info.orientation + orientation) % 360;
* }
* mParameters.setRotation(rotation);
* }
*
*
* @param rotation The rotation angle in degrees relative to the
* orientation of the camera. Rotation can only be 0,
* 90, 180 or 270.
* @throws IllegalArgumentException if rotation value is invalid.
* @see android.view.OrientationEventListener
* @see #getCameraInfo(int, CameraInfo)
*/
public void setRotation(int rotation) {
if (rotation == 0 || rotation == 90 || rotation == 180
|| rotation == 270) {
set(KEY_ROTATION, Integer.toString(rotation));
} else {
throw new IllegalArgumentException(
"Invalid rotation=" + rotation);
}
}
/**
* Sets GPS latitude coordinate. This will be stored in JPEG EXIF
* header.
*
* @param latitude GPS latitude coordinate.
*/
public void setGpsLatitude(double latitude) {
set(KEY_GPS_LATITUDE, Double.toString(latitude));
}
/**
* Sets GPS longitude coordinate. This will be stored in JPEG EXIF
* header.
*
* @param longitude GPS longitude coordinate.
*/
public void setGpsLongitude(double longitude) {
set(KEY_GPS_LONGITUDE, Double.toString(longitude));
}
/**
* Sets GPS altitude. This will be stored in JPEG EXIF header.
*
* @param altitude GPS altitude in meters.
*/
public void setGpsAltitude(double altitude) {
set(KEY_GPS_ALTITUDE, Double.toString(altitude));
}
/**
* Sets GPS timestamp. This will be stored in JPEG EXIF header.
*
* @param timestamp GPS timestamp (UTC in seconds since January 1,
* 1970).
*/
public void setGpsTimestamp(long timestamp) {
set(KEY_GPS_TIMESTAMP, Long.toString(timestamp));
}
/**
* Sets GPS processing method. The method will be stored in a UTF-8 string up to 31 bytes
* long, in the JPEG EXIF header.
*
* @param processing_method The processing method to get this location.
*/
public void setGpsProcessingMethod(String processing_method) {
set(KEY_GPS_PROCESSING_METHOD, processing_method);
}
/**
* Removes GPS latitude, longitude, altitude, and timestamp from the
* parameters.
*/
public void removeGpsData() {
remove(KEY_GPS_LATITUDE);
remove(KEY_GPS_LONGITUDE);
remove(KEY_GPS_ALTITUDE);
remove(KEY_GPS_TIMESTAMP);
remove(KEY_GPS_PROCESSING_METHOD);
}
/**
* Gets the current white balance setting.
*
* @return current white balance. null if white balance setting is not
* supported.
* @see #WHITE_BALANCE_AUTO
* @see #WHITE_BALANCE_INCANDESCENT
* @see #WHITE_BALANCE_FLUORESCENT
* @see #WHITE_BALANCE_WARM_FLUORESCENT
* @see #WHITE_BALANCE_DAYLIGHT
* @see #WHITE_BALANCE_CLOUDY_DAYLIGHT
* @see #WHITE_BALANCE_TWILIGHT
* @see #WHITE_BALANCE_SHADE
*
*/
public String getWhiteBalance() {
return get(KEY_WHITE_BALANCE);
}
/**
* Sets the white balance. Changing the setting will release the
* auto-white balance lock. It is recommended not to change white
* balance and AWB lock at the same time.
*
* @param value new white balance.
* @see #getWhiteBalance()
* @see #setAutoWhiteBalanceLock(boolean)
*/
public void setWhiteBalance(String value) {
String oldValue = get(KEY_WHITE_BALANCE);
if (same(value, oldValue)) return;
set(KEY_WHITE_BALANCE, value);
set(KEY_AUTO_WHITEBALANCE_LOCK, FALSE);
}
/**
* Gets the supported white balance.
*
* @return a list of supported white balance. null if white balance
* setting is not supported.
* @see #getWhiteBalance()
*/
public List