Android APIs
public abstract class

CameraDevice

extends Object
implements AutoCloseable
java.lang.Object
   ↳ android.hardware.camera2.CameraDevice

Class Overview

The CameraDevice class is a representation of a single camera connected to an Android device, allowing for fine-grain control of image capture and post-processing at high frame rates.

Your application must declare the Camera permission in its manifest in order to access camera devices.

A given camera device may provide support at one of two levels: limited or full. If a device only supports the limited level, then Camera2 exposes a feature set that is roughly equivalent to the older Camera API, although with a cleaner and more efficient interface. Devices that implement the full level of support provide substantially improved capabilities over the older camera API. Applications that target the limited level devices will run unchanged on the full-level devices; if your application requires a full-level device for proper operation, declare the "android.hardware.camera2.full" feature in your manifest.

Summary

Nested Classes
class CameraDevice.StateCallback A callback objects for receiving updates about the state of a camera device. 
Constants
int TEMPLATE_MANUAL A basic template for direct application control of capture parameters.
int TEMPLATE_PREVIEW Create a request suitable for a camera preview window.
int TEMPLATE_RECORD Create a request suitable for video recording.
int TEMPLATE_STILL_CAPTURE Create a request suitable for still image capture.
int TEMPLATE_VIDEO_SNAPSHOT Create a request suitable for still image capture while recording video.
int TEMPLATE_ZERO_SHUTTER_LAG Create a request suitable for zero shutter lag still capture.
Public Methods
abstract void close()
Close the connection to this camera device as quickly as possible.
abstract CaptureRequest.Builder createCaptureRequest(int templateType)

Create a CaptureRequest.Builder for new capture requests, initialized with template for a target use case.

abstract void createCaptureSession(List<Surface> outputs, CameraCaptureSession.StateCallback callback, Handler handler)

Create a new camera capture session by providing the target output set of Surfaces to the camera device.

abstract String getId()
Get the ID of this camera device.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.AutoCloseable

Constants

public static final int TEMPLATE_MANUAL

Added in API level 21

A basic template for direct application control of capture parameters. All automatic control is disabled (auto-exposure, auto-white balance, auto-focus), and post-processing parameters are set to preview quality. The manual capture parameters (exposure, sensitivity, and so on) are set to reasonable defaults, but should be overriden by the application depending on the intended use case.

Constant Value: 6 (0x00000006)

public static final int TEMPLATE_PREVIEW

Added in API level 21

Create a request suitable for a camera preview window. Specifically, this means that high frame rate is given priority over the highest-quality post-processing. These requests would normally be used with the setRepeatingRequest(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler) method.

Constant Value: 1 (0x00000001)

public static final int TEMPLATE_RECORD

Added in API level 21

Create a request suitable for video recording. Specifically, this means that a stable frame rate is used, and post-processing is set for recording quality. These requests would commonly be used with the setRepeatingRequest(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler) method.

Constant Value: 3 (0x00000003)

public static final int TEMPLATE_STILL_CAPTURE

Added in API level 21

Create a request suitable for still image capture. Specifically, this means prioritizing image quality over frame rate. These requests would commonly be used with the capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler) method.

Constant Value: 2 (0x00000002)

public static final int TEMPLATE_VIDEO_SNAPSHOT

Added in API level 21

Create a request suitable for still image capture while recording video. Specifically, this means maximizing image quality without disrupting the ongoing recording. These requests would commonly be used with the capture(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler) method while a request based on TEMPLATE_RECORD is is in use with setRepeatingRequest(CaptureRequest, CameraCaptureSession.CaptureCallback, Handler).

Constant Value: 4 (0x00000004)

public static final int TEMPLATE_ZERO_SHUTTER_LAG

Added in API level 21

Create a request suitable for zero shutter lag still capture. This means means maximizing image quality without compromising preview frame rate. AE/AWB/AF should be on auto mode.

Constant Value: 5 (0x00000005)

Public Methods

public abstract void close ()

Added in API level 21

Close the connection to this camera device as quickly as possible.

Immediately after this call, all calls to the camera device or active session interface will throw a IllegalStateException, except for calls to close(). Once the device has fully shut down, the onClosed(CameraDevice) callback will be called, and the camera is free to be re-opened.

Immediately after this call, besides the final onClosed(CameraDevice) calls, no further callbacks from the device or the active session will occur, and any remaining submitted capture requests will be discarded, as if abortCaptures() had been called, except that no success or failure callbacks will be invoked.

public abstract CaptureRequest.Builder createCaptureRequest (int templateType)

Added in API level 21

Create a CaptureRequest.Builder for new capture requests, initialized with template for a target use case. The settings are chosen to be the best options for the specific camera device, so it is not recommended to reuse the same request for a different camera device; create a builder specific for that device and template and override the settings as desired, instead.

Parameters
templateType An enumeration selecting the use case for this request; one of the CameraDevice.TEMPLATE_ values.
Returns
  • a builder for a capture request, initialized with default settings for that template, and no output streams
Throws
IllegalArgumentException if the templateType is not in the list of supported templates.
CameraAccessException if the camera device is no longer connected or has encountered a fatal error
IllegalStateException if the camera device has been closed

public abstract void createCaptureSession (List<Surface> outputs, CameraCaptureSession.StateCallback callback, Handler handler)

Added in API level 21

Create a new camera capture session by providing the target output set of Surfaces to the camera device.

The active capture session determines the set of potential output Surfaces for the camera device for each capture request. A given request may use all or a only some of the outputs. Once the CameraCaptureSession is created, requests can be can be submitted with capture, captureBurst, setRepeatingRequest, or setRepeatingBurst.

Surfaces suitable for inclusion as a camera output can be created for various use cases and targets:

The camera device will query each Surface's size and formats upon this call, so they must be set to a valid setting at this time.

It can take several hundred milliseconds for the session's configuration to complete, since camera hardware may need to be powered on or reconfigured. Once the configuration is complete and the session is ready to actually capture data, the provided CameraCaptureSession.StateCallback's onConfigured(CameraCaptureSession) callback will be called.

If a prior CameraCaptureSession already exists when a new one is created, the previous session is closed. Any in-progress capture requests made on the prior session will be completed before the new session is configured and is able to start capturing its own requests. To minimize the transition time, the abortCaptures() call can be used to discard the remaining requests for the prior capture session before a new one is created. Note that once the new session is created, the old one can no longer have its captures aborted.

Using larger resolution outputs, or more outputs, can result in slower output rate from the device.

Configuring a session with an empty or null list will close the current session, if any. This can be used to release the current session's target surfaces for another use.

While any of the sizes from getOutputSizes(int) can be used when a single output stream is configured, a given camera device may not be able to support all combination of sizes, formats, and targets when multiple outputs are configured at once. The tables below list the maximum guaranteed resolutions for combinations of streams and targets, given the capabilities of the camera device.

If an application tries to create a session using a set of targets that exceed the limits described in the below tables, one of three possibilities may occur. First, the session may be successfully created and work normally. Second, the session may be successfully created, but the camera device won't meet the frame rate guarantees as described in getOutputMinFrameDuration(int, Size). Or third, if the output set cannot be used at all, session creation will fail entirely, with onConfigureFailed(CameraCaptureSession) being invoked.

For the type column, PRIV refers to any target whose available sizes are found using getOutputSizes(Class) with no direct application-visible format, YUV refers to a target Surface using the YUV_420_888 format, JPEG refers to the JPEG format, and RAW refers to the RAW_SENSOR format.

For the maximum size column, PREVIEW refers to the best size match to the device's screen resolution, or to 1080p (1920x1080), whichever is smaller. RECORD refers to the camera device's maximum supported recording resolution, as determined by CamcorderProfile. And MAXIMUM refers to the camera device's maximum output resolution for that format or target from getOutputSizes(int).

To use these tables, determine the number and the formats/targets of outputs needed, and find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes that can be used; it is guaranteed that for those targets, the listed sizes and anything smaller from the list given by getOutputSizes(int) can be successfully used to create a session. For example, if a row indicates that a 8 megapixel (MP) YUV_420_888 output can be used together with a 2 MP PRIV output, then a session can be created with targets [8 MP YUV, 2 MP PRIV] or targets [2 MP YUV, 2 MP PRIV]; but a session with targets [8 MP YUV, 4 MP PRIV], targets [4 MP YUV, 4 MP PRIV], or targets [8 MP PRIV, 2 MP YUV] would not be guaranteed to work, unless some other row of the table lists such a combination.

Legacy devices (INFO_SUPPORTED_HARDWARE_LEVEL == LEGACY) support at least the following stream combinations:

LEGACY-level guaranteed configurations
Target 1 Target 2 Target 3 Sample use case(s)
TypeMax size TypeMax size TypeMax size
PRIVMAXIMUM Simple preview, GPU video processing, or no-preview video recording.
JPEGMAXIMUM No-viewfinder still image capture.
YUV MAXIMUM In-application video/image processing.
PRIVPREVIEW JPEGMAXIMUM Standard still imaging.
YUV PREVIEW JPEGMAXIMUM In-app processing plus still capture.
PRIVPREVIEW PRIVPREVIEW Standard recording.
PRIVPREVIEW YUV PREVIEW Preview plus in-app processing.
PRIVPREVIEW YUV PREVIEW JPEGMAXIMUM Still capture plus in-app processing.

Limited-capability (INFO_SUPPORTED_HARDWARE_LEVEL == LIMITED) devices support at least the following stream combinations in addition to those for LEGACY devices:

LIMITED-level additional guaranteed configurations
Target 1Target 2Target 3 Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax size
PRIVPREVIEW PRIVRECORD High-resolution video recording with preview.
PRIVPREVIEW YUV RECORD High-resolution in-app video processing with preview.
YUV PREVIEW YUV RECORD Two-input in-app video processing.
PRIVPREVIEW PRIVRECORD JPEGRECORD High-resolution recording with video snapshot.
PRIVPREVIEW YUV RECORD JPEGRECORD High-resolution in-app processing with video snapshot.
YUV PREVIEW YUV PREVIEW JPEGMAXIMUM Two-input in-app processing with still capture.

FULL-capability (INFO_SUPPORTED_HARDWARE_LEVEL == FULL) devices support at least the following stream combinations in addition to those for LIMITED devices:

FULL-capability additional guaranteed configurations
Target 1Target 2Target 3 Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax size
PRIVPREVIEW PRIVMAXIMUM Maximum-resolution GPU processing with preview.
PRIVPREVIEW YUV MAXIMUM Maximum-resolution in-app processing with preview.
YUV PREVIEW YUV MAXIMUM Maximum-resolution two-input in-app processsing.
PRIVPREVIEW PRIVPREVIEW JPEGMAXIMUM Video recording with maximum-size video snapshot
YUV 640x480 PRIVPREVIEW YUV MAXIMUM Standard video recording plus maximum-resolution in-app processing.
YUV 640x480 YUV PREVIEW YUV MAXIMUM Preview plus two-input maximum-resolution in-app processing.

RAW-capability (REQUEST_AVAILABLE_CAPABILITIES includes RAW) devices additionally support at least the following stream combinations on both FULL and LIMITED devices:

RAW-capability additional guaranteed configurations
Target 1Target 2Target 3 Sample use case(s)
TypeMax sizeTypeMax sizeTypeMax size
RAW MAXIMUM No-preview DNG capture.
PRIVPREVIEW RAW MAXIMUM Standard DNG capture.
YUV PREVIEW RAW MAXIMUM In-app processing plus DNG capture.
PRIVPREVIEW PRIVPREVIEW RAW MAXIMUM Video recording with DNG capture.
PRIVPREVIEW YUV PREVIEW RAW MAXIMUM Preview with in-app processing and DNG capture.
YUV PREVIEW YUV PREVIEW RAW MAXIMUM Two-input in-app processing plus DNG capture.
PRIVPREVIEW JPEGMAXIMUM RAW MAXIMUM Still capture with simultaneous JPEG and DNG.
YUV PREVIEW JPEGMAXIMUM RAW MAXIMUM In-app processing with simultaneous JPEG and DNG.

BURST-capability (REQUEST_AVAILABLE_CAPABILITIES includes BURST_CAPTURE) devices support at least the below stream combinations in addition to those for LIMITED devices. Note that all FULL-level devices support the BURST capability, and the below list is a strict subset of the list for FULL-level devices, so this table is only relevant for LIMITED-level devices that support the BURST_CAPTURE capability.

BURST-capability additional guaranteed configurations
Target 1Target 2Sample use case(s)
TypeMax sizeTypeMax size
PRIVPREVIEW PRIVMAXIMUM Maximum-resolution GPU processing with preview.
PRIVPREVIEW YUV MAXIMUM Maximum-resolution in-app processing with preview.
YUV PREVIEW YUV MAXIMUM Maximum-resolution two-input in-app processsing.

Since the capabilities of camera devices vary greatly, a given camera device may support target combinations with sizes outside of these guarantees, but this can only be tested for by attempting to create a session with such targets.

Parameters
outputs The new set of Surfaces that should be made available as targets for captured image data.
callback The callback to notify about the status of the new capture session.
handler The handler on which the callback should be invoked, or null to use the current thread's looper.
Throws
IllegalArgumentException if the set of output Surfaces do not meet the requirements, the callback is null, or the handler is null but the current thread has no looper.
CameraAccessException if the camera device is no longer connected or has encountered a fatal error
IllegalStateException if the camera device has been closed

public abstract String getId ()

Added in API level 21

Get the ID of this camera device.

This matches the ID given to openCamera(String, CameraDevice.StateCallback, Handler) to instantiate this this camera device.

This ID can be used to query the camera device's fixed properties with getCameraCharacteristics(String).

This method can be called even if the device has been closed or has encountered a serious error.

Returns
  • the ID for this camera device