CameraDevice

See also:

• CameraManager.openCamera
• Manifest.permission.CAMERA
• CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL

AUDIO_RESTRICTION_NONE

public static final int AUDIO_RESTRICTION_NONE

No vibration or sound muting for this camera device. This is the default mode for all camera devices.

Constant Value: 0 (0x00000000)

AUDIO_RESTRICTION_VIBRATION

public static final int AUDIO_RESTRICTION_VIBRATION

Mute vibration from ringtones, alarms or notifications while this camera device is in use.

Constant Value: 1 (0x00000001)

AUDIO_RESTRICTION_VIBRATION_SOUND

public static final int AUDIO_RESTRICTION_VIBRATION_SOUND

Mute vibration and sound from ringtones, alarms or notifications while this camera device is in use.

As of API level 37, this option will also turn off any lights on the device if they are bright enough to interfere with camera photos or recordings.

Constant Value: 3 (0x00000003)

TEMPLATE_MANUAL

public static final int TEMPLATE_MANUAL

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 overridden by the application depending on the intended use case. This template is guaranteed to be supported on camera devices that support the MANUAL_SENSOR capability.

Constant Value: 6 (0x00000006)

TEMPLATE_PREVIEW

public static final int TEMPLATE_PREVIEW

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 CameraCaptureSession.setRepeatingRequest method. This template is guaranteed to be supported on all camera devices.

Constant Value: 1 (0x00000001)

TEMPLATE_RECORD

public static final int TEMPLATE_RECORD

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 CameraCaptureSession.setRepeatingRequest method. This template is guaranteed to be supported on all camera devices except DEPTH_OUTPUT devices that are not BACKWARD_COMPATIBLE.

Constant Value: 3 (0x00000003)

TEMPLATE_STILL_CAPTURE

public static final int TEMPLATE_STILL_CAPTURE

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 CameraCaptureSession.capture method. This template is guaranteed to be supported on all camera devices except DEPTH_OUTPUT devices that are not BACKWARD_COMPATIBLE.

Constant Value: 2 (0x00000002)

TEMPLATE_VIDEO_SNAPSHOT

public static final int TEMPLATE_VIDEO_SNAPSHOT

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 CameraCaptureSession.capture method while a request based on TEMPLATE_RECORD is is in use with CameraCaptureSession.setRepeatingRequest. This template is guaranteed to be supported on all camera devices except legacy devices (CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL == LEGACY) and DEPTH_OUTPUT devices that are not BACKWARD_COMPATIBLE.

Constant Value: 4 (0x00000004)

TEMPLATE_ZERO_SHUTTER_LAG

public static final int TEMPLATE_ZERO_SHUTTER_LAG

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. This is intended for application-operated ZSL. For device-operated ZSL, use CaptureRequest.CONTROL_ENABLE_ZSL if available. This template is guaranteed to be supported on camera devices that support the PRIVATE_REPROCESSING capability or the YUV_REPROCESSING capability.

Constant Value: 5 (0x00000005)

close

public abstract void close ()

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 StateCallback.onClosed callback will be called, and the camera is free to be re-opened.

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

createCaptureRequest

public CaptureRequest.Builder createCaptureRequest (int templateType, 
                Set<String> physicalCameraIdSet)

Create a CaptureRequest.Builder for new capture requests, initialized with template for a target use case. This methods allows clients to pass physical camera ids which can be used to customize the request for a specific physical camera. The settings are chosen to be the best options for the specific logical camera device. If additional physical camera ids are passed, then they will also use the same settings template. Clients can further modify individual camera settings by calling CaptureRequest.Builder.setPhysicalCameraKey.

Individual physical camera settings will only be honored for camera session that was initialized with corresponding physical camera id output configuration OutputConfiguration.setPhysicalCameraId and the same output targets are also attached in the request by CaptureRequest.Builder.addTarget.

The output is undefined for any logical camera streams in case valid physical camera settings are attached.

createCaptureRequest

public abstract CaptureRequest.Builder createCaptureRequest (int templateType)

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.

createCaptureSession

public void createCaptureSession (SessionConfiguration config)

Create a new CameraCaptureSession using a SessionConfiguration helper object that aggregates all supported parameters.

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 only some of the outputs. Once the CameraCaptureSession is created, requests 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:

• For drawing to a SurfaceView: Once the SurfaceView's Surface is created, set the size of the Surface with SurfaceHolder.setFixedSize(int, int) to be one of the sizes returned by getOutputSizes(SurfaceHolder.class) and then obtain the Surface by calling 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 SurfaceTexture: Set the size of the SurfaceTexture with SurfaceTexture.setDefaultBufferSize(int, int) to be one of the sizes returned by getOutputSizes(SurfaceTexture.class) before creating a Surface from the SurfaceTexture with Surface.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.
• For recording with MediaCodec: Call MediaCodec.createInputSurface() after configuring the media codec to use one of the sizes returned by getOutputSizes(MediaCodec.class)
• For recording with MediaRecorder: Call MediaRecorder.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.
• For access to RAW, uncompressed YUV, or compressed JPEG data in the application: Create an ImageReader object with one of the supported output formats given by StreamConfigurationMap.getOutputFormats(), setting its size to one of the corresponding supported sizes by passing the chosen output format into StreamConfigurationMap.getOutputSizes(int). Then obtain a Surface from it with 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 CameraCaptureSession.StateCallback's CameraCaptureSession.StateCallback.onConfigured callback will be called.

If a prior CameraCaptureSession already exists when this method is called, the previous session will no longer be able to accept new capture requests and will be closed. Any in-progress capture requests made on the prior session will be completed before it's closed. CameraCaptureSession.StateCallback.onConfigured for the new session may be invoked before CameraCaptureSession.StateCallback.onClosed is invoked for the prior session. Once the new session is configured, it is able to start capturing its own requests. To minimize the transition time, the 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.

This function throws an IllegalArgumentException if called with a SessionConfiguration lacking state callbacks or valid output surfaces. The only exceptions are deferred SurfaceView or SurfaceTexture outputs. See OutputConfiguration.OutputConfiguration(Size,Class) for details.

Regular capture

While any of the sizes from 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. These are valid for when the input configuration is not set and therefore no reprocessing is active.

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 StreamConfigurationMap.getOutputMinFrameDuration. Or third, if the output set cannot be used at all, session creation will fail entirely, with CameraCaptureSession.StateCallback.onConfigureFailed being invoked.

For the type column, PRIV refers to any target whose available sizes are found using StreamConfigurationMap.getOutputSizes(Class) with no direct application-visible format, YUV refers to a target Surface using the ImageFormat.YUV_420_888 format, JPEG refers to the ImageFormat.JPEG format, and RAW refers to the ImageFormat.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 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 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 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-level guaranteed configurations

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

LIMITED-level additional guaranteed configurations

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

FULL-level additional guaranteed configurations

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

RAW-capability additional guaranteed configurations

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

BURST-capability additional guaranteed configurations

BURST-capability (CameraCharacteristics.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.

LEVEL-3 additional guaranteed configurations

LEVEL-3 (CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL == LEVEL_3) support at least the following stream combinations in addition to the combinations for FULL and for RAW capability (CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES includes RAW):

Concurrent stream guaranteed configurations

BACKWARD_COMPATIBLE devices capable of streaming concurrently with other devices as described by CameraManager.getConcurrentCameraIds() have the following guaranteed streams (when streaming concurrently with other devices)

Note: The sizes mentioned for these concurrent streams are the maximum sizes guaranteed to be supported. Sizes smaller than these, obtained by StreamConfigurationMap.getOutputSizes for a particular format, are supported as well.

Devices which are not backwards-compatible, support a mandatory single stream of size sVGA with image format DEPTH16 during concurrent operation.

For guaranteed concurrent stream configurations:

sVGA refers to the camera device's maximum resolution for that format from StreamConfigurationMap.getOutputSizes or VGA resolution (640X480) whichever is lower.

s720p refers to the camera device's maximum resolution for that format from StreamConfigurationMap.getOutputSizes or 720p(1280X720) whichever is lower.

s1440p refers to the camera device's maximum resolution for that format from StreamConfigurationMap.getOutputSizes or 1440p(1920X1440) whichever is lower.

MONOCHROME-capability (CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES includes MONOCHROME) devices supporting Y8 support substituting YUV streams with Y8 in all guaranteed stream combinations for the device's hardware level and capabilities.

Clients can access the above mandatory stream combination tables via MandatoryStreamCombination.

Devices capable of outputting HEIC formats (StreamConfigurationMap.getOutputFormats contains ImageFormat.HEIC) will support substituting JPEG streams with HEIC in all guaranteed stream combinations for the device's hardware level and capabilities. Calling createCaptureSession with both JPEG and HEIC outputs is not supported.

LEGACY-level additional guaranteed combinations with multi-resolution outputs

Devices capable of multi-resolution output for a particular format ( MultiResolutionStreamConfigurationMap.getOutputInfo(int) returns a non-empty list) support using MultiResolutionImageReader for MAXIMUM resolution streams of that format for all mandatory stream combinations. For example, if a LIMITED camera device supports multi-resolution output streams for both JPEG and PRIVATE, in addition to the stream configurations in the LIMITED and Legacy table above, the camera device supports the following guaranteed stream combinations (MULTI_RES in the Max size column refers to a MultiResolutionImageReader created based on the variable max resolutions supported):

LIMITED-level additional guaranteed configurations with multi-resolution outputs

Additional guaranteed combinations for ULTRA_HIGH_RESOLUTION sensors

Devices with the ULTRA_HIGH_RESOLUTION_SENSOR capability have some additional guarantees which clients can take advantage of:

Here, SC Map, refers to the StreamConfigurationMap, the target stream sizes must be chosen from. DEFAULT refers to the default sensor pixel mode StreamConfigurationMap and MAX_RES refers to the maximum resolution StreamConfigurationMap. For MAX_RES streams, MAX in the Max size column refers to the maximum size from StreamConfigurationMap.getOutputSizes and StreamConfigurationMap.getHighResolutionOutputSizes. Note: The same capture request must not mix targets from StreamConfigurationMaps corresponding to different sensor pixel modes.

10-bit output additional guaranteed configurations

10-bit output capable CameraMetadata.REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT devices support at least the following stream combinations:

Here PRIV can be either 8 or 10-bit ImageFormat.PRIVATE pixel format. YUV can be either ImageFormat.YUV_420_888 or ImageFormat.YCBCR_P010. 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. MAXIMUM refers to the camera device's maximum output resolution for that format or target from StreamConfigurationMap.getOutputSizes(int). Do note that invalid combinations such as having a camera surface configured to use pixel format ImageFormat.YUV_420_888 with a 10-bit profile will cause a capture session initialization failure.

ImageFormat.JPEG_R may also be supported if advertised by StreamConfigurationMap. When initializing a capture session that includes a Jpeg/R camera output clients must consider the following items w.r.t. the 10-bit mandatory stream combination table:

• To generate the compressed Jpeg/R image a single ImageFormat.YCBCR_P010 output will be used internally by the camera device.
• On camera devices that are able to support concurrent 10 and 8-bit capture requests see DynamicRangeProfiles.getProfileCaptureRequestConstraints(long) an extra ImageFormat.JPEG will also be configured internally to help speed up the encoding process.

STREAM_USE_CASE capability additional guaranteed configurations

Devices with the STREAM_USE_CASE capability (CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES includes CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE) support below additional stream combinations:

STREAM_USE_CASE_CROPPED_RAW capability additional guaranteed configurations

Devices that include the CameraMetadata.SCALER_AVAILABLE_STREAM_USE_CASES_CROPPED_RAW stream use-case in CameraCharacteristics.SCALER_AVAILABLE_STREAM_USE_CASES, support the additional stream combinations below:

Preview stabilization guaranteed stream configurations

For devices where CameraCharacteristics.CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES includes CameraMetadata.CONTROL_VIDEO_STABILIZATION_MODE_PREVIEW_STABILIZATION, the following stream combinations are guaranteed, for CaptureRequests where CaptureRequest.CONTROL_VIDEO_STABILIZATION_MODE is set to CameraMetadata.CONTROL_VIDEO_STABILIZATION_MODE_PREVIEW_STABILIZATION

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. MAXIMUM refers to the camera device's maximum output resolution for that format or target from StreamConfigurationMap.getOutputSizes(int).

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 calling isSessionConfigurationSupported(SessionConfiguration) or attempting to create a session with such targets.

Exception on 176x144 (QCIF) resolution: Camera devices usually have a fixed capability for downscaling from larger resolution to smaller, and the QCIF resolution sometimes is not fully supported due to this limitation on devices with high-resolution image sensors. Therefore, trying to configure a QCIF resolution stream together with any other stream larger than 1920x1080 resolution (either width or height) might not be supported, and cap