java.lang.Object | |
↳ | android.hardware.Camera |
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.
To access the device camera, you must declare the
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:
open(int)
.
getParameters()
.
Camera.Parameters
object and call
setParameters(Camera.Parameters)
.
setDisplayOrientation(int)
.
SurfaceHolder
to
setPreviewDisplay(SurfaceHolder)
. Without a surface, the camera
will be unable to start the preview.
startPreview()
to start updating the
preview surface. Preview must be started before you can take a picture.
takePicture(Camera.ShutterCallback, Camera.PictureCallback, Camera.PictureCallback, Camera.PictureCallback)
to
capture a photo. Wait for the callbacks to provide the actual image data.
startPreview()
again first.
stopPreview()
to stop updating the preview surface.
release()
to release the camera for
use by other applications. Applications should release the camera
immediately in onPause()
(and re-open()
it in onResume()
).
To quickly switch to video recording mode, use these steps:
unlock()
to allow the media process to access the camera.
setCamera(Camera)
.
See MediaRecorder
information about video recording.
reconnect()
to re-acquire
and re-lock the camera.
stopPreview()
and release()
as described above.
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 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.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Camera.Area | 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. |
||||||||||
Camera.AutoFocusCallback | Callback interface used to notify on completion of camera auto focus. | ||||||||||
Camera.AutoFocusMoveCallback | Callback interface used to notify on auto focus start and stop. | ||||||||||
Camera.CameraInfo | Information about a camera | ||||||||||
Camera.ErrorCallback | Callback interface for camera error notification. | ||||||||||
Camera.Face | Information about a face identified through camera face detection. | ||||||||||
Camera.FaceDetectionListener | Callback interface for face detected in the preview frame. | ||||||||||
Camera.OnZoomChangeListener | Callback interface for zoom changes during a smooth zoom operation. | ||||||||||
Camera.Parameters | Camera service settings. | ||||||||||
Camera.PictureCallback | Callback interface used to supply image data from a photo capture. | ||||||||||
Camera.PreviewCallback | Callback interface used to deliver copies of preview frames as they are displayed. | ||||||||||
Camera.ShutterCallback | Callback interface used to signal the moment of actual image capture. | ||||||||||
Camera.Size | Image size (width and height dimensions). |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | ACTION_NEW_PICTURE | Broadcast Action: A new picture is taken by the camera, and the entry of the picture has been added to the media store. | |||||||||
String | ACTION_NEW_VIDEO | Broadcast Action: A new video is recorded by the camera, and the entry of the video has been added to the media store. | |||||||||
int | CAMERA_ERROR_SERVER_DIED | Media server died. | |||||||||
int | CAMERA_ERROR_UNKNOWN | Unspecified camera error. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds a pre-allocated buffer to the preview callback buffer queue.
| |||||||||||
Starts camera auto-focus and registers a callback function to run when
the camera is focused.
| |||||||||||
Cancels any auto-focus function in progress.
| |||||||||||
Enable or disable the default shutter sound when taking a picture. | |||||||||||
Returns the information about a particular camera.
| |||||||||||
Returns the number of physical cameras available on this device.
| |||||||||||
Returns the current settings for this Camera service.
| |||||||||||
Re-locks the camera to prevent other processes from accessing it.
| |||||||||||
Creates a new Camera object to access a particular hardware camera.
| |||||||||||
Creates a new Camera object to access the first back-facing camera on the
device.
| |||||||||||
Reconnects to the camera service after another process used it.
| |||||||||||
Disconnects and releases the Camera object resources.
| |||||||||||
Sets camera auto-focus move callback.
| |||||||||||
Set the clockwise rotation of preview display in degrees.
| |||||||||||
Registers a callback to be invoked when an error occurs.
| |||||||||||
Registers a listener to be notified about the faces detected in the
preview frame.
| |||||||||||
Installs a callback to be invoked for the next preview frame in addition to displaying it on the screen. | |||||||||||
Changes the settings for this Camera service.
| |||||||||||
Installs a callback to be invoked for every preview frame in addition to displaying them on the screen. | |||||||||||
Installs a callback to be invoked for every preview frame, using
buffers supplied with | |||||||||||
Sets the
Surface to be used for live preview. | |||||||||||
Sets the
SurfaceTexture to be used for live preview. | |||||||||||
Registers a listener to be notified when the zoom value is updated by the
camera driver during smooth zoom.
| |||||||||||
Starts the face detection.
| |||||||||||
Starts capturing and drawing preview frames to the screen.
| |||||||||||
Zooms to the requested value smoothly.
| |||||||||||
Stops the face detection.
| |||||||||||
Stops capturing and drawing preview frames to the surface, and
resets the camera for a future call to
startPreview() . | |||||||||||
Stops the smooth zoom.
| |||||||||||
Equivalent to takePicture(shutter, raw, null, jpeg).
| |||||||||||
Triggers an asynchronous image capture.
| |||||||||||
Unlocks the camera to allow another process to access it.
|
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Invoked when the garbage collector has detected that this instance is no longer reachable.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Broadcast Action: A new picture is taken by the camera, and the entry of
the picture has been added to the media store.
getData()
is URI of the picture.
Broadcast Action: A new video is recorded by the camera, and the entry
of the video has been added to the media store.
getData()
is URI of the video.
Media server died. In this case, the application must release the Camera object and instantiate a new one.
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 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.
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
getPreviewSize()
. Bytes per pixel can be
computed from getBitsPerPixel(int)
/
8, using the image format from
getPreviewFormat()
.
If using the YV12
format, the
size can be calculated using the equations listed in
setPreviewFormat(int)
.
This method is only necessary when
setPreviewCallbackWithBuffer(PreviewCallback)
is used. When
setPreviewCallback(PreviewCallback)
or
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.
callbackBuffer | the buffer to add to the queue. The size of the buffer must match the values described above. |
---|
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 startPreview()
and before stopPreview()
).
Callers should check
getFocusMode()
to determine if
this method should be called. If the camera does not support auto-focus,
it is a no-op and 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
FLASH_MODE_OFF
, flash may be
fired during auto-focus, depending on the driver and camera hardware.
Auto-exposure lock getAutoExposureLock()
and auto-white balance locks 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 stopPreview()
, or triggering still
image capture with 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
MediaActionSound
to properly play back an autofocus
success sound to the user.
cb | the callback to run |
---|
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.
Enable or disable the default shutter sound when taking a picture.
By default, the camera plays the system-defined camera shutter sound
when takePicture(Camera.ShutterCallback, Camera.PictureCallback, Camera.PictureCallback)
is called. Using this method, the shutter sound
can be disabled. It is strongly recommended that an alternative shutter
sound is played in the Camera.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. canDisableShutterSound
can be used to determine whether the device will allow the shutter sound
to be disabled.
enabled | whether the camera should play the system shutter sound
when takePicture is called. |
---|
true
if the shutter sound state was successfully
changed. false
if the shutter sound state could not be
changed. true
is also returned if shutter sound playback
is already set to the requested state.Returns the information about a particular camera.
If getNumberOfCameras()
returns N, the valid id is 0 to N-1.
Returns the number of physical cameras available on this device.
Returns the current settings for this Camera service.
If modifications are made to the returned Parameters, they must be passed
to setParameters(Camera.Parameters)
to take effect.
Re-locks the camera to prevent other processes from accessing it.
Camera objects are locked by default unless unlock()
is
called. Normally reconnect()
is used instead.
Since API level 14, camera is automatically locked for applications in
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.
RuntimeException | if the camera cannot be re-locked (for example, if the camera is still in use by another process). |
---|
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 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 AsyncTask
) to avoid
blocking the main application UI thread.
cameraId | the hardware camera to access, between 0 and
getNumberOfCameras() -1. |
---|
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). |
---|
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.
Reconnects to the camera service after another process used it.
After 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
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.
IOException | if a connection cannot be re-established (for example, if the camera is still in use by another process). |
---|
Disconnects and releases the Camera object resources.
You must call this as soon as you're done with the Camera object.
Sets camera auto-focus move callback.
cb | the callback to run |
---|
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 onPreviewFrame(byte[], Camera)
, 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.
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); }
Starting from API level 14, this method can be called when preview is active.
degrees | the angle that the picture will be rotated clockwise. Valid values are 0, 90, 180, and 270. The starting position is 0 (landscape). |
---|
Registers a callback to be invoked when an error occurs.
cb | The callback to run |
---|
Registers a listener to be notified about the faces detected in the preview frame.
listener | the listener to notify |
---|
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 MediaActionSound
to
properly indicate image capture or recording start/stop to the user.
cb | a callback object that receives a copy of the next preview frame, or null to stop receiving callbacks. |
---|
Changes the settings for this Camera service.
params | the Parameters to use for this Camera service |
---|
RuntimeException | if any parameter is invalid or not supported. |
---|
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 MediaActionSound
to
properly indicate image capture or recording start/stop to the user.
cb | a callback object that receives a copy of each preview frame, or null to stop receiving callbacks. |
---|
Installs a callback to be invoked for every preview frame, using
buffers supplied with 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
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, setPreviewCallback(Camera.PreviewCallback)
is called,
or setOneShotPreviewCallback(Camera.PreviewCallback)
is
called.
If you are using the preview data to create video or still images,
strongly consider using MediaActionSound
to
properly indicate image capture or recording start/stop to the user.
cb | a callback object that receives a copy of the preview frame, or null to stop receiving callbacks and clear the buffer queue. |
---|
Sets the 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 setPreviewTexture(SurfaceTexture)
.
The SurfaceHolder
must already contain a surface when this
method is called. If you are using SurfaceView
,
you will need to register a SurfaceHolder.Callback
with
addCallback(SurfaceHolder.Callback)
and wait for
surfaceCreated(SurfaceHolder)
before
calling setPreviewDisplay() or starting preview.
This method must be called before 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.
holder | containing the Surface on which to place the preview, or null to remove the preview surface |
---|
IOException | if the method fails (for example, if the surface is unavailable or unsuitable). |
---|
Sets the 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 setPreviewDisplay(SurfaceHolder)
.
This method must be called before 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 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 MediaActionSound
to
properly indicate image capture or recording start/stop to the user.
surfaceTexture | the SurfaceTexture to which the preview
images are to be sent or null to remove the current preview surface
texture |
---|
IOException | if the method fails (for example, if the surface texture is unavailable or unsuitable). |
---|
Registers a listener to be notified when the zoom value is updated by the camera driver during smooth zoom.
listener | the listener to notify |
---|
Starts the face detection. This should be called after preview is started.
The camera will notify Camera.FaceDetectionListener
of the detected
faces in the preview frame. The detected faces may be the same as the
previous ones. Applications should call stopFaceDetection()
to
stop the face detection. This method is supported if getMaxNumDetectedFaces()
returns a number larger than 0.
If the face detection has started, apps should not call this again.
When the face detection is running, setWhiteBalance(String)
,
setFocusAreas(List)
, and setMeteringAreas(List)
have no effect. The camera uses the detected faces to do auto-white balance,
auto exposure, and autofocus.
If the apps call 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 cancelAutoFocus()
, the face callbacks will also resume.
After calling takePicture(Camera.ShutterCallback, Camera.PictureCallback, Camera.PictureCallback)
or stopPreview()
, and then resuming
preview with startPreview()
, the apps should call this method
again to resume face detection.
IllegalArgumentException | if the face detection is unsupported. |
---|---|
RuntimeException | if the method fails or the face detection is already running. |
Starts capturing and drawing preview frames to the screen.
Preview will not actually start until a surface is supplied
with setPreviewDisplay(SurfaceHolder)
or
setPreviewTexture(SurfaceTexture)
.
If setPreviewCallback(Camera.PreviewCallback)
,
setOneShotPreviewCallback(Camera.PreviewCallback)
, or
setPreviewCallbackWithBuffer(Camera.PreviewCallback)
were
called, onPreviewFrame(byte[], Camera)
will be called when preview data becomes available.
Zooms to the requested value smoothly. The driver will notify Camera.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
onZoomChange(int, boolean, Camera)
method will be called three times with zoom values 1, 2, and 3.
Applications can call 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 isSmoothZoomSupported()
returns true.
value | zoom value. The valid range is 0 to getMaxZoom() . |
---|
IllegalArgumentException | if the zoom value is invalid. |
---|---|
RuntimeException | if the method fails. |
Stops capturing and drawing preview frames to the surface, and
resets the camera for a future call to startPreview()
.
Stops the smooth zoom. Applications should wait for the Camera.OnZoomChangeListener
to know when the zoom is actually stopped. This
method is supported if isSmoothZoomSupported()
is true.
RuntimeException | if the method fails. |
---|
Equivalent to takePicture(shutter, raw, null, jpeg).
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 will be null if there is no raw image callback buffer available or the raw image callback buffer is not large enough to hold the raw image). The postview callback occurs when a scaled, fully processed postview image is available (NOTE: not all hardware supports this). 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 is only valid when preview is active (after
startPreview()
). Preview will be stopped after the image is
taken; callers must call startPreview()
again if they want to
re-start preview or take more pictures. This should not be called between
start()
and
stop()
.
After calling this method, you must not call startPreview()
or take another picture until the JPEG callback has returned.
shutter | the callback for image capture moment, or null |
---|---|
raw | the callback for raw (uncompressed) image data, or null |
postview | callback with postview image data, may be null |
jpeg | the callback for JPEG image data, or null |
Unlocks the camera to allow another process to access it.
Normally, the camera is locked to the process with an active Camera
object until 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 reconnect()
to reclaim the camera.
This must be done before calling
setCamera(Camera)
. This cannot be
called after recording starts.
If you are not recording video, you probably do not need this method.
RuntimeException | if the camera cannot be unlocked. |
---|
Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.
Note that objects that override finalize
are significantly more expensive than
objects that don't. Finalizers may be run a long time after the object is no longer
reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup.
Note also that finalizers are run on a single VM-wide finalizer thread,
so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary
for a class that has a native peer and needs to call a native method to destroy that peer.
Even then, it's better to provide an explicit close
method (and implement
Closeable
), and insist that callers manually dispose of instances. This
works well for something like files, but less well for something like a BigInteger
where typical calling code would have to deal with lots of temporaries. Unfortunately,
code that creates lots of temporaries is the worst kind of code from the point of view of
the single finalizer thread.
If you must use finalizers, consider at least providing your own
ReferenceQueue
and having your own thread process that queue.
Unlike constructors, finalizers are not automatically chained. You are responsible for
calling super.finalize()
yourself.
Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.