android.hardware.camera2
API for new
applications.@Deprecated public class Camera extends Object
To access the device camera, you must declare the
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:
open(int)
.
getParameters()
.
Camera.Parameters
object and call
setParameters(Camera.Parameters)
.
setDisplayOrientation(int)
to ensure correct orientation of preview.
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 Activity.onPause()
(and re-open()
it in Activity.onResume()
).
To quickly switch to video recording mode, use these steps:
unlock()
to allow the media process to access the camera.
MediaRecorder.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.
Modifier and Type | Class and Description |
---|---|
static class |
Camera.Area
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static interface |
Camera.AutoFocusCallback
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static interface |
Camera.AutoFocusMoveCallback
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static class |
Camera.CameraInfo
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static interface |
Camera.ErrorCallback
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static class |
Camera.Face
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static interface |
Camera.FaceDetectionListener
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static interface |
Camera.OnZoomChangeListener
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
class |
Camera.Parameters
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static interface |
Camera.PictureCallback
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static interface |
Camera.PreviewCallback
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
static interface |
Camera.ShutterCallback
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
class |
Camera.Size
Deprecated.
We recommend using the new
android.hardware.camera2 API for new
applications. |
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_NEW_PICTURE
Deprecated.
This broadcast is no longer delivered by the system; use
JobInfo.Builder .JobInfo.Builder.addTriggerContentUri(android.app.job.JobInfo.TriggerContentUri)
instead.
Broadcast Action: A new picture is taken by the camera, and the entry of
the picture has been added to the media store.
Intent.getData() is URI of the picture. |
static String |
ACTION_NEW_VIDEO
Deprecated.
This broadcast is no longer delivered by the system; use
JobInfo.Builder .JobInfo.Builder.addTriggerContentUri(android.app.job.JobInfo.TriggerContentUri)
instead.
Broadcast Action: A new video is recorded by the camera, and the entry
of the video has been added to the media store.
Intent.getData() is URI of the video. |
static int |
CAMERA_ERROR_EVICTED
Deprecated.
Camera was disconnected due to use by higher priority user.
|
static int |
CAMERA_ERROR_SERVER_DIED
Deprecated.
Media server died.
|
static int |
CAMERA_ERROR_UNKNOWN
Deprecated.
Unspecified camera error.
|
static int |
CAMERA_HAL_API_VERSION_1_0
Deprecated.
Camera HAL device API version 1.0
|
Modifier and Type | Method and Description |
---|---|
void |
addCallbackBuffer(byte[] callbackBuffer)
Deprecated.
Adds a pre-allocated buffer to the preview callback buffer queue.
|
void |
addRawImageCallbackBuffer(byte[] callbackBuffer)
Deprecated.
Adds a pre-allocated buffer to the raw image callback buffer queue.
|
void |
autoFocus(Camera.AutoFocusCallback cb)
Deprecated.
Starts camera auto-focus and registers a callback function to run when
the camera is focused.
|
int |
cameraInitUnspecified(int cameraId)
Deprecated.
Connect to the camera service using #connectLegacy
This acts the same as normal except that it will return
the detailed error code if open fails instead of
converting everything into
NO_INIT . |
void |
cancelAutoFocus()
Deprecated.
Cancels any auto-focus function in progress.
|
static boolean |
checkInitErrors(int err)
Deprecated.
|
Allocation |
createPreviewAllocation(RenderScript rs,
int usage)
Deprecated.
Create a
RenderScript
Allocation to use as a
destination of preview callback frames. |
boolean |
disableShutterSound()
Deprecated.
Disable the shutter sound unconditionally.
|
boolean |
enableShutterSound(boolean enabled)
Deprecated.
Enable or disable the default shutter sound when taking a picture.
|
protected void |
finalize()
Deprecated.
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
static void |
getCameraInfo(int cameraId,
Camera.CameraInfo cameraInfo)
Deprecated.
Returns the information about a particular camera.
|
static Camera.Parameters |
getEmptyParameters()
Deprecated.
Returns an empty
Camera.Parameters for testing purpose. |
static int |
getNumberOfCameras()
Deprecated.
Returns the number of physical cameras available on this device.
|
Camera.Parameters |
getParameters()
Deprecated.
Returns the current settings for this Camera service.
|
static Camera.Parameters |
getParametersCopy(Camera.Parameters parameters)
Deprecated.
Returns a copied
Camera.Parameters ; for shim use only. |
void |
lock()
Deprecated.
Re-locks the camera to prevent other processes from accessing it.
|
static Camera |
open()
Deprecated.
Creates a new Camera object to access the first back-facing camera on the
device.
|
static Camera |
open(int cameraId)
Deprecated.
Creates a new Camera object to access a particular hardware camera.
|
static Camera |
openLegacy(int cameraId,
int halVersion)
Deprecated.
Creates a new Camera object to access a particular hardware camera with
given hal API version.
|
static Camera |
openUninitialized()
Deprecated.
|
boolean |
previewEnabled()
Deprecated.
Return current preview state.
|
void |
reconnect()
Deprecated.
Reconnects to the camera service after another process used it.
|
void |
release()
Deprecated.
Disconnects and releases the Camera object resources.
|
void |
setAutoFocusMoveCallback(Camera.AutoFocusMoveCallback cb)
Deprecated.
Sets camera auto-focus move callback.
|
void |
setDisplayOrientation(int degrees)
Deprecated.
Set the clockwise rotation of preview display in degrees.
|
void |
setErrorCallback(Camera.ErrorCallback cb)
Deprecated.
Registers a callback to be invoked when an error occurs.
|
void |
setFaceDetectionListener(Camera.FaceDetectionListener listener)
Deprecated.
Registers a listener to be notified about the faces detected in the
preview frame.
|
void |
setOneShotPreviewCallback(Camera.PreviewCallback cb)
Deprecated.
Installs a callback to be invoked for the next preview frame in
addition to displaying it on the screen.
|
void |
setParameters(Camera.Parameters params)
Deprecated.
Changes the settings for this Camera service.
|
void |
setPreviewCallback(Camera.PreviewCallback cb)
Deprecated.
Installs a callback to be invoked for every preview frame in addition
to displaying them on the screen.
|
void |
setPreviewCallbackAllocation(Allocation previewAllocation)
Deprecated.
Set an
Allocation as the
target of preview callback data. |
void |
setPreviewCallbackWithBuffer(Camera.PreviewCallback cb)
Deprecated.
Installs a callback to be invoked for every preview frame, using
buffers supplied with
addCallbackBuffer(byte[]) , in addition to
displaying them on the screen. |
void |
setPreviewDisplay(SurfaceHolder holder)
Deprecated.
Sets the
Surface to be used for live preview. |
void |
setPreviewSurface(Surface surface)
Deprecated.
|
void |
setPreviewTexture(SurfaceTexture surfaceTexture)
Deprecated.
Sets the
SurfaceTexture to be used for live preview. |
void |
setZoomChangeListener(Camera.OnZoomChangeListener listener)
Deprecated.
Registers a listener to be notified when the zoom value is updated by the
camera driver during smooth zoom.
|
void |
startFaceDetection()
Deprecated.
Starts the face detection.
|
void |
startPreview()
Deprecated.
Starts capturing and drawing preview frames to the screen.
|
void |
startSmoothZoom(int value)
Deprecated.
Zooms to the requested value smoothly.
|
void |
stopFaceDetection()
Deprecated.
Stops the face detection.
|
void |
stopPreview()
Deprecated.
Stops capturing and drawing preview frames to the surface, and
resets the camera for a future call to
startPreview() . |
void |
stopSmoothZoom()
Deprecated.
Stops the smooth zoom.
|
void |
takePicture(Camera.ShutterCallback shutter,
Camera.PictureCallback raw,
Camera.PictureCallback jpeg)
Deprecated.
Equivalent to takePicture(shutter, raw, null, jpeg).
|
void |
takePicture(Camera.ShutterCallback shutter,
Camera.PictureCallback raw,
Camera.PictureCallback postview,
Camera.PictureCallback jpeg)
Deprecated.
Triggers an asynchronous image capture.
|
void |
unlock()
Deprecated.
Unlocks the camera to allow another process to access it.
|
@Deprecated public static final String ACTION_NEW_PICTURE
JobInfo.Builder
.JobInfo.Builder.addTriggerContentUri(android.app.job.JobInfo.TriggerContentUri)
instead.
Broadcast Action: A new picture is taken by the camera, and the entry of
the picture has been added to the media store.
Intent.getData()
is URI of the picture.@Deprecated public static final String ACTION_NEW_VIDEO
JobInfo.Builder
.JobInfo.Builder.addTriggerContentUri(android.app.job.JobInfo.TriggerContentUri)
instead.
Broadcast Action: A new video is recorded by the camera, and the entry
of the video has been added to the media store.
Intent.getData()
is URI of the video.public static final int CAMERA_HAL_API_VERSION_1_0
public static final int CAMERA_ERROR_UNKNOWN
Camera.ErrorCallback
,
Constant Field Valuespublic static final int CAMERA_ERROR_EVICTED
Camera.ErrorCallback
,
Constant Field Valuespublic static final int CAMERA_ERROR_SERVER_DIED
Camera.ErrorCallback
,
Constant Field Valuespublic static int getNumberOfCameras()
public static void getCameraInfo(int cameraId, Camera.CameraInfo cameraInfo)
getNumberOfCameras()
returns N, the valid id is 0 to N-1.public static Camera open(int cameraId)
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).DevicePolicyManager.getCameraDisabled(android.content.ComponentName)
public static Camera open()
open(int)
public static Camera openLegacy(int cameraId, int halVersion)
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.halVersion
- The HAL API version this camera device to be opened as.IllegalArgumentException
- if the halVersion
is invalidRuntimeException
- if opening the camera fails (for example, if the
camera is in use by another process or device policy manager has disabled
the camera).DevicePolicyManager.getCameraDisabled(android.content.ComponentName)
,
CAMERA_HAL_API_VERSION_1_0
public int cameraInitUnspecified(int cameraId)
This acts the same as normal except that it will return
the detailed error code if open fails instead of
converting everything into NO_INIT
.
Intended to use by the camera2 shim only, do not use this for other code.
NO_ERROR
on successpublic static boolean checkInitErrors(int err)
public static Camera openUninitialized()
protected void finalize()
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.
public final void release()
You must call this as soon as you're done with the Camera object.
public final void unlock()
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
MediaRecorder.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.public final void lock()
unlock()
is
called. Normally reconnect()
is used instead.
Since API level 14, camera is automatically locked for applications in
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.
RuntimeException
- if the camera cannot be re-locked (for
example, if the camera is still in use by another process).public final void reconnect() throws IOException
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
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.
IOException
- if a connection cannot be re-established (for
example, if the camera is still in use by another process).public final void setPreviewDisplay(SurfaceHolder holder) throws IOException
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(android.graphics.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
SurfaceHolder.addCallback(SurfaceHolder.Callback)
and wait for
SurfaceHolder.Callback#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 surfaceIOException
- if the method fails (for example, if the surface
is unavailable or unsuitable).public final void setPreviewSurface(Surface surface) throws IOException
IOException
public final void setPreviewTexture(SurfaceTexture surfaceTexture) throws IOException
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(android.view.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 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 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
textureIOException
- if the method fails (for example, if the surface
texture is unavailable or unsuitable).MediaActionSound
,
SurfaceTexture
,
TextureView
public final void startPreview()
setPreviewDisplay(SurfaceHolder)
or
setPreviewTexture(SurfaceTexture)
.
If setPreviewCallback(Camera.PreviewCallback)
,
setOneShotPreviewCallback(Camera.PreviewCallback)
, or
setPreviewCallbackWithBuffer(Camera.PreviewCallback)
were
called, Camera.PreviewCallback.onPreviewFrame(byte[], Camera)
will be called when preview data becomes available.
public final void stopPreview()
startPreview()
.public final boolean previewEnabled()
public final void setPreviewCallback(Camera.PreviewCallback cb)
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.MediaActionSound
public final void setOneShotPreviewCallback(Camera.PreviewCallback cb)
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.MediaActionSound
public final void setPreviewCallbackWithBuffer(Camera.PreviewCallback cb)
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.addCallbackBuffer(byte[])
,
MediaActionSound
public final void addCallbackBuffer(byte[] callbackBuffer)
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
Camera.Parameters.getPreviewSize()
. Bytes per pixel can be
computed from ImageFormat.getBitsPerPixel(int)
/
8, using the image format from
Camera.Parameters.getPreviewFormat()
.
If using the ImageFormat.YV12
format, the
size can be calculated using the equations listed in
Camera.Parameters.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.setPreviewCallbackWithBuffer(PreviewCallback)
public final void addRawImageCallbackBuffer(byte[] callbackBuffer)
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 Camera.Parameters.getPictureSize()
. Bytes per pixel
can be computed from
ImageFormat.getBitsPerPixel(int)
/ 8,
using the image format from Camera.Parameters.getPreviewFormat()
.
This method is only necessary when the PictureCallbck for raw image
is used while calling 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.
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.{@hide}
public final Allocation createPreviewAllocation(RenderScript rs, int usage) throws RSIllegalArgumentException
Create a RenderScript
Allocation
to use as a
destination of preview callback frames. Use
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 rsGetElementAtYuv_*
accessor methods. Its size will be based on the current
preview size
configured for this
camera.
rs
- the RenderScript context for this Allocation.usage
- additional usage flags to set for the Allocation. The usage
flag Allocation.USAGE_IO_INPUT
will always
be set on the created Allocation, but additional flags may be provided
here.RSIllegalArgumentException
- if the usage flags are not compatible
with an YUV Allocation.setPreviewCallbackAllocation(android.renderscript.Allocation)
public final void setPreviewCallbackAllocation(Allocation previewAllocation) throws IOException
Set an 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 createPreviewAllocation
method.
Setting a preview allocation will disable any active preview callbacks
set by setPreviewCallback
or
setPreviewCallbackWithBuffer
, and
vice versa. Using a preview allocation still requires an active standard
preview target to be set, either with
setPreviewTexture
or
setPreviewDisplay
.
To be notified when new frames are available to the Allocation, use
Allocation.setIoInputNotificationHandler
. To
update the frame currently accessible from the Allocation to the latest
preview frame, call
Allocation.ioReceive
.
To disable preview into the Allocation, call this method with a
null
parameter.
Once a preview allocation is set, the preview size set by
setPreviewSize
cannot be changed. If
you wish to change the preview size, first remove the preview allocation
by calling setPreviewCallbackAllocation(null)
, then change the
preview size, create a new preview Allocation with
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 MediaActionSound
to
properly indicate image capture or recording start/stop to the user.
previewAllocation
- the allocation to use as destination for previewIOException
- if configuring the camera to use the Allocation for
preview fails.IllegalArgumentException
- if the Allocation's dimensions or other
parameters don't meet the requirements.createPreviewAllocation(android.renderscript.RenderScript, int)
,
setPreviewCallback(android.hardware.Camera.PreviewCallback)
,
setPreviewCallbackWithBuffer(android.hardware.Camera.PreviewCallback)
public final void autoFocus(Camera.AutoFocusCallback cb)
startPreview()
and before stopPreview()
).
Callers should check
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 Camera.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
Camera.Parameters.FLASH_MODE_OFF
, flash may be
fired during auto-focus, depending on the driver and camera hardware.
Auto-exposure lock Camera.Parameters.getAutoExposureLock()
and auto-white balance locks 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 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 runcancelAutoFocus()
,
Camera.Parameters.setAutoExposureLock(boolean)
,
Camera.Parameters.setAutoWhiteBalanceLock(boolean)
,
MediaActionSound
public final void cancelAutoFocus()
autoFocus(Camera.AutoFocusCallback)
public void setAutoFocusMoveCallback(Camera.AutoFocusMoveCallback cb)
cb
- the callback to runpublic final void takePicture(Camera.ShutterCallback shutter, Camera.PictureCallback raw, Camera.PictureCallback jpeg)
public final void takePicture(Camera.ShutterCallback shutter, Camera.PictureCallback raw, Camera.PictureCallback postview, Camera.PictureCallback jpeg)
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
MediaRecorder.start()
and
MediaRecorder.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 nullraw
- the callback for raw (uncompressed) image data, or nullpostview
- callback with postview image data, may be nulljpeg
- the callback for JPEG image data, or nullpublic final void startSmoothZoom(int value)
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
Camera.OnZoomChangeListener.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 Camera.Parameters.isSmoothZoomSupported()
returns true.value
- zoom value. The valid range is 0 to Camera.Parameters.getMaxZoom()
.IllegalArgumentException
- if the zoom value is invalid.RuntimeException
- if the method fails.setZoomChangeListener(OnZoomChangeListener)
public final void stopSmoothZoom()
Camera.OnZoomChangeListener
to know when the zoom is actually stopped. This
method is supported if Camera.Parameters.isSmoothZoomSupported()
is true.RuntimeException
- if the method fails.public final void setDisplayOrientation(int degrees)
This does not affect the order of byte array passed in Camera.PreviewCallback.onPreviewFrame(byte[], android.hardware.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.
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.
degrees
- the angle that the picture will be rotated clockwise.
Valid values are 0, 90, 180, and 270.setPreviewDisplay(SurfaceHolder)
public final boolean enableShutterSound(boolean enabled)
Enable or disable the default shutter sound when taking a picture.
By default, the camera plays the system-defined camera shutter sound
when takePicture(android.hardware.Camera.ShutterCallback, android.hardware.Camera.PictureCallback, android.hardware.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. Camera.CameraInfo.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.takePicture(android.hardware.Camera.ShutterCallback, android.hardware.Camera.PictureCallback, android.hardware.Camera.PictureCallback)
,
Camera.CameraInfo.canDisableShutterSound
,
Camera.ShutterCallback
public final boolean disableShutterSound()
This is only guaranteed to work for legacy cameras
(i.e. initialized with cameraInitUnspecified(int)
). Trying to call this on
a regular camera will force a conditional check in the camera service.
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.public final void setZoomChangeListener(Camera.OnZoomChangeListener listener)
listener
- the listener to notifystartSmoothZoom(int)
public final void setFaceDetectionListener(Camera.FaceDetectionListener listener)
listener
- the listener to notifystartFaceDetection()
public final void startFaceDetection()
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 Camera.Parameters.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, Camera.Parameters.setWhiteBalance(String)
,
Camera.Parameters.setFocusAreas(List)
, and Camera.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 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.Camera.FaceDetectionListener
,
stopFaceDetection()
,
Camera.Parameters.getMaxNumDetectedFaces()
public final void stopFaceDetection()
startFaceDetection()
public final void setErrorCallback(Camera.ErrorCallback cb)
cb
- The callback to runpublic void setParameters(Camera.Parameters params)
params
- the Parameters to use for this Camera serviceRuntimeException
- if any parameter is invalid or not supported.getParameters()
public Camera.Parameters getParameters()
setParameters(Camera.Parameters)
to take effect.setParameters(Camera.Parameters)
public static Camera.Parameters getEmptyParameters()
Camera.Parameters
for testing purpose.public static Camera.Parameters getParametersCopy(Camera.Parameters parameters)
Camera.Parameters
; for shim use only.parameters
- a non-null
parametersparameters
.NullPointerException
- if parameters
was null