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 {@link CameraCaptureSession#capture capture},
{@link CameraCaptureSession#captureBurst captureBurst},
{@link CameraCaptureSession#setRepeatingRequest setRepeatingRequest}, or
{@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}.
Surfaces suitable for inclusion as a camera output can be created for
various use cases and targets:
- For drawing to a {@link android.view.SurfaceView SurfaceView}: Once the SurfaceView's
Surface is {@link android.view.SurfaceHolder.Callback#surfaceCreated created}, set the size
of the Surface with {@link android.view.SurfaceHolder#setFixedSize} to be one of the sizes
returned by {@link StreamConfigurationMap#getOutputSizes(Class)
getOutputSizes(SurfaceHolder.class)} and then obtain the Surface by calling {@link
android.view.SurfaceHolder#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.
- For accessing through an OpenGL texture via a {@link android.graphics.SurfaceTexture
SurfaceTexture}: Set the size of the SurfaceTexture with {@link
android.graphics.SurfaceTexture#setDefaultBufferSize} to be one of the sizes returned by
{@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(SurfaceTexture.class)}
before creating a Surface from the SurfaceTexture with {@link Surface#Surface}. 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.
- For recording with {@link android.media.MediaCodec}: Call
{@link android.media.MediaCodec#createInputSurface} after configuring
the media codec to use one of the sizes returned by
{@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaCodec.class)}
- For recording with {@link android.media.MediaRecorder}: Call
{@link android.media.MediaRecorder#getSurface} after configuring the media recorder to use
one of the sizes returned by
{@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaRecorder.class)},
or configuring it to use one of the supported
{@link android.media.CamcorderProfile CamcorderProfiles}.
- For efficient YUV processing with {@link android.renderscript}:
Create a RenderScript
{@link android.renderscript.Allocation Allocation} with a supported YUV
type, the IO_INPUT flag, and one of the sizes returned by
{@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(Allocation.class)},
Then obtain the Surface with
{@link android.renderscript.Allocation#getSurface}.
- For access to raw, uncompressed JPEG data in the application: Create an
{@link android.media.ImageReader} object with one of the supported output formats given by
{@link StreamConfigurationMap#getOutputFormats()}, setting its size to one of the
corresponding supported sizes by passing the chosen output format into
{@link StreamConfigurationMap#getOutputSizes(int)}. Then obtain a
{@link android.view.Surface} from it with {@link android.media.ImageReader#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
{@link CameraCaptureSession.StateCallback}'s
{@link CameraCaptureSession.StateCallback#onConfigured} 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 {@link CameraCaptureSession#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 {@link StreamConfigurationMap#getOutputSizes} 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
{@link StreamConfigurationMap#getOutputMinFrameDuration}. Or third, if the output set
cannot be used at all, session creation will fail entirely, with
{@link CameraCaptureSession.StateListener#onConfigureFailed} being invoked.
For the type column, {@code PRIV} refers to any target whose available sizes are found
using {@link StreamConfigurationMap#getOutputSizes(Class)} with no direct application-visible
format, {@code YUV} refers to a target Surface using the
{@link android.graphics.ImageFormat#YUV_420_888} format, {@code JPEG} refers to the
{@link android.graphics.ImageFormat#JPEG} format, and {@code RAW} refers to the
{@link android.graphics.ImageFormat#RAW_SENSOR} format.
For the maximum size column, {@code PREVIEW} refers to the best size match to the
device's screen resolution, or to 1080p ({@code 1920x1080}), whichever is
smaller. {@code RECORD} refers to the camera device's maximum supported recording resolution,
as determined by {@link android.media.CamcorderProfile}. And {@code MAXIMUM} refers to the
camera device's maximum output resolution for that format or target from
{@link StreamConfigurationMap#getOutputSizes}.
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 {@link StreamConfigurationMap#getOutputSizes} 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 {@code PRIV} output, then a session
can be created with targets {@code [8 MP YUV, 2 MP PRIV]} or targets {@code [2 MP YUV, 2 MP
PRIV]}; but a session with targets {@code [8 MP YUV, 4 MP PRIV]}, targets {@code [4 MP YUV, 4
MP PRIV]}, or targets {@code [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 ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}
{@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY 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 |
| {@code PRIV} | {@code MAXIMUM} | | | Simple preview, GPU video processing, or no-preview video recording. |
| {@code JPEG} | {@code MAXIMUM} | | | No-viewfinder still image capture. |
| {@code YUV } | {@code MAXIMUM} | | | In-application video/image processing. |
| {@code PRIV} | {@code PREVIEW} | {@code JPEG} | {@code MAXIMUM} | | Standard still imaging. |
| {@code YUV } | {@code PREVIEW} | {@code JPEG} | {@code MAXIMUM} | | In-app processing plus still capture. |
| {@code PRIV} | {@code PREVIEW} | {@code PRIV} | {@code PREVIEW} | | Standard recording. |
| {@code PRIV} | {@code PREVIEW} | {@code YUV } | {@code PREVIEW} | | Preview plus in-app processing. |
| {@code PRIV} | {@code PREVIEW} | {@code YUV } | {@code PREVIEW} | {@code JPEG} | {@code MAXIMUM} | Still capture plus in-app processing. |
Limited-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}
{@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices
support at least the following stream combinations in addition to those for
{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY 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 |
|---|
| {@code PRIV} | {@code PREVIEW} | {@code PRIV} | {@code RECORD } | | High-resolution video recording with preview. |
| {@code PRIV} | {@code PREVIEW} | {@code YUV } | {@code RECORD } | | High-resolution in-app video processing with preview. |
| {@code YUV } | {@code PREVIEW} | {@code YUV } | {@code RECORD } | | Two-input in-app video processing. |
| {@code PRIV} | {@code PREVIEW} | {@code PRIV} | {@code RECORD } | {@code JPEG} | {@code RECORD } | High-resolution recording with video snapshot. |
| {@code PRIV} | {@code PREVIEW} | {@code YUV } | {@code RECORD } | {@code JPEG} | {@code RECORD } | High-resolution in-app processing with video snapshot. |
| {@code YUV } | {@code PREVIEW} | {@code YUV } | {@code PREVIEW} | {@code JPEG} | {@code MAXIMUM} | Two-input in-app processing with still capture. |
FULL-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}
{@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices
support at least the following stream combinations in addition to those for
{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED 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 |
|---|
| {@code PRIV} | {@code PREVIEW} | {@code PRIV} | {@code MAXIMUM} | | Maximum-resolution GPU processing with preview. |
| {@code PRIV} | {@code PREVIEW} | {@code YUV } | {@code MAXIMUM} | | Maximum-resolution in-app processing with preview. |
| {@code YUV } | {@code PREVIEW} | {@code YUV } | {@code MAXIMUM} | | Maximum-resolution two-input in-app processsing. |
| {@code PRIV} | {@code PREVIEW} | {@code PRIV} | {@code PREVIEW} | {@code JPEG} | {@code MAXIMUM} | Video recording with maximum-size video snapshot |
| {@code YUV } | {@code 640x480} | {@code PRIV} | {@code PREVIEW} | {@code YUV } | {@code MAXIMUM} | Standard video recording plus maximum-resolution in-app processing. |
| {@code YUV } | {@code 640x480} | {@code YUV } | {@code PREVIEW} | {@code YUV } | {@code MAXIMUM} | Preview plus two-input maximum-resolution in-app processing. |
RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes
{@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support
at least the following stream combinations on both
{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and
{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED 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 |
|---|
| {@code RAW } | {@code MAXIMUM} | | | No-preview DNG capture. |
| {@code PRIV} | {@code PREVIEW} | {@code RAW } | {@code MAXIMUM} | | Standard DNG capture. |
| {@code YUV } | {@code PREVIEW} | {@code RAW } | {@code MAXIMUM} | | In-app processing plus DNG capture. |
| {@code PRIV} | {@code PREVIEW} | {@code PRIV} | {@code PREVIEW} | {@code RAW } | {@code MAXIMUM} | Video recording with DNG capture. |
| {@code PRIV} | {@code PREVIEW} | {@code YUV } | {@code PREVIEW} | {@code RAW } | {@code MAXIMUM} | Preview with in-app processing and DNG capture. |
| {@code YUV } | {@code PREVIEW} | {@code YUV } | {@code PREVIEW} | {@code RAW } | {@code MAXIMUM} | Two-input in-app processing plus DNG capture. |
| {@code PRIV} | {@code PREVIEW} | {@code JPEG} | {@code MAXIMUM} | {@code RAW } | {@code MAXIMUM} | Still capture with simultaneous JPEG and DNG. |
| {@code YUV } | {@code PREVIEW} | {@code JPEG} | {@code MAXIMUM} | {@code RAW } | {@code MAXIMUM} | In-app processing with simultaneous JPEG and DNG. |
BURST-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes
{@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices
support at least the below stream combinations in addition to those for
{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED 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 |
|---|
| {@code PRIV} | {@code PREVIEW} | {@code PRIV} | {@code MAXIMUM} | Maximum-resolution GPU processing with preview. |
| {@code PRIV} | {@code PREVIEW} | {@code YUV } | {@code MAXIMUM} | Maximum-resolution in-app processing with preview. |
| {@code YUV } | {@code PREVIEW} | {@code YUV } | {@code 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.
