java.lang.Object | |
↳ | android.hardware.camera2.CameraDevice |
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.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
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 | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Close the connection to this camera device as quickly as possible.
| |||||||||||
Create a | |||||||||||
Create a new camera capture session by providing the target output set of Surfaces to the camera device. | |||||||||||
Get the ID of this camera device.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
From interface
java.lang.AutoCloseable
|
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.
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.
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.
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.
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)
.
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.
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.
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.
templateType | An enumeration selecting the use case for this request; one of the CameraDevice.TEMPLATE_ values. |
---|
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 |
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:
SurfaceView
: Once the SurfaceView's
Surface is created
, set the size
of the Surface with setFixedSize(int, int)
to be one of the sizes
returned by getOutputSizes(SurfaceHolder.class)
and then obtain the Surface by calling getSurface()
. If the size is not set by the application, it will
be rounded to the nearest supported size less than 1080p, by the camera device.SurfaceTexture
: Set the size of the SurfaceTexture with setDefaultBufferSize(int, int)
to be one of the sizes returned by
getOutputSizes(SurfaceTexture.class)
before creating a Surface from the SurfaceTexture with Surface(SurfaceTexture)
. If the size
is not set by the application, it will be set to be the smallest supported size less than
1080p, by the camera device.MediaCodec
: Call
createInputSurface()
after configuring
the media codec to use one of the sizes returned by
getOutputSizes(MediaCodec.class)
MediaRecorder
: Call
getSurface()
after configuring the media recorder to use
one of the sizes returned by
getOutputSizes(MediaRecorder.class)
,
or configuring it to use one of the supported
CamcorderProfiles
.android.renderscript
:
Create a RenderScript
Allocation
with a supported YUV
type, the IO_INPUT flag, and one of the sizes returned by
getOutputSizes(Allocation.class)
,
Then obtain the Surface with
getSurface()
.ImageReader
object with one of the supported output formats given by
getOutputFormats()
, setting its size to one of the
corresponding supported sizes by passing the chosen output format into
getOutputSizes(int)
. Then obtain a
Surface
from it with getSurface()
.
If the ImageReader size is not set to a supported size, it will be rounded to a supported
size less than 1080p by the camera device.
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) | |||
Type | Max size | Type | Max size | Type | Max size | |
PRIV | MAXIMUM | Simple preview, GPU video processing, or no-preview video recording. | ||||
JPEG | MAXIMUM | No-viewfinder still image capture. | ||||
YUV | MAXIMUM | In-application video/image processing. | ||||
PRIV | PREVIEW | JPEG | MAXIMUM | Standard still imaging. | ||
YUV | PREVIEW | JPEG | MAXIMUM | In-app processing plus still capture. | ||
PRIV | PREVIEW | PRIV | PREVIEW | Standard recording. | ||
PRIV | PREVIEW | YUV | PREVIEW | Preview plus in-app processing. | ||
PRIV | PREVIEW | YUV | PREVIEW | JPEG | MAXIMUM | 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 1 | Target 2 | Target 3 | Sample use case(s) | |||
Type | Max size | Type | Max size | Type | Max size | |
PRIV | PREVIEW | PRIV | RECORD | High-resolution video recording with preview. | ||
PRIV | PREVIEW | YUV | RECORD | High-resolution in-app video processing with preview. | ||
YUV | PREVIEW | YUV | RECORD | Two-input in-app video processing. | ||
PRIV | PREVIEW | PRIV | RECORD | JPEG | RECORD | High-resolution recording with video snapshot. |
PRIV | PREVIEW | YUV | RECORD | JPEG | RECORD | High-resolution in-app processing with video snapshot. |
YUV | PREVIEW | YUV | PREVIEW | JPEG | MAXIMUM | 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 1 | Target 2 | Target 3 | Sample use case(s) | |||
Type | Max size | Type | Max size | Type | Max size | |
PRIV | PREVIEW | PRIV | MAXIMUM | Maximum-resolution GPU processing with preview. | ||
PRIV | PREVIEW | YUV | MAXIMUM | Maximum-resolution in-app processing with preview. | ||
YUV | PREVIEW | YUV | MAXIMUM | Maximum-resolution two-input in-app processsing. | ||
PRIV | PREVIEW | PRIV | PREVIEW | JPEG | MAXIMUM | Video recording with maximum-size video snapshot |
YUV | 640x480 | PRIV | PREVIEW | 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 1 | Target 2 | Target 3 | Sample use case(s) | |||
Type | Max size | Type | Max size | Type | Max size | |
RAW | MAXIMUM | No-preview DNG capture. | ||||
PRIV | PREVIEW | RAW | MAXIMUM | Standard DNG capture. | ||
YUV | PREVIEW | RAW | MAXIMUM | In-app processing plus DNG capture. | ||
PRIV | PREVIEW | PRIV | PREVIEW | RAW | MAXIMUM | Video recording with DNG capture. |
PRIV | PREVIEW | 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. |
PRIV | PREVIEW | JPEG | MAXIMUM | RAW | MAXIMUM | Still capture with simultaneous JPEG and DNG. |
YUV | PREVIEW | JPEG | MAXIMUM | 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 1 | Target 2 | Sample use case(s) | ||
Type | Max size | Type | Max size | |
PRIV | PREVIEW | PRIV | MAXIMUM | Maximum-resolution GPU processing with preview. |
PRIV | PREVIEW | 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.
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 . |
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 |
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.