CameraDeviceSetup

Kotlin |Java

abstract class CameraDeviceSetup

kotlin.Any
↳	android.hardware.camera2.CameraDevice.CameraDeviceSetup

CameraDeviceSetup is a limited representation of CameraDevice that can be used to query device specific information which would otherwise need a CameraDevice instance. This class can be constructed without calling android.hardware.camera2.CameraManager#openCamera and paying the latency cost of CameraDevice creation. Use CameraManager#getCameraDeviceSetup to get an instance of this class.

Can only be instantiated for camera devices for which CameraManager#isCameraDeviceSetupSupported returns true.

Summary

Public methods
abstract CaptureRequest.Builder	`createCaptureRequest(templateType: Int)` Create a `CaptureRequest.Builder` for new capture requests, initialized with a template for target use case.
abstract String	`getId()` Get the ID of this camera device.
abstract CameraCharacteristics	`getSessionCharacteristics(sessionConfig: SessionConfiguration)` Get camera characteristics for a particular session configuration for this camera device.
abstract Boolean	`isSessionConfigurationSupported(config: SessionConfiguration)` Checks whether a particular `SessionConfiguration` is supported by the camera device.
abstract Unit	`openCamera(executor: Executor, callback: CameraDevice.StateCallback)` Utility function to forward the call to `CameraManager#openCamera(String, Executor, StateCallback)`.

Public methods

createCaptureRequest

Added in API level 35

abstract fun createCaptureRequest(templateType: Int): CaptureRequest.Builder

Create a CaptureRequest.Builder for new capture requests, initialized with a template for 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.

Supported if CameraCharacteristics#INFO_SESSION_CONFIGURATION_QUERY_VERSION is at least android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM. If less or equal to android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, this function throws an UnsupportedOperationException.

Parameters

templateType Int: An enumeration selecting the use case for this request. Not all template types are supported on every device. See the documentation for each template type for details. Value is android.hardware.camera2.CameraDevice#TEMPLATE_PREVIEW, android.hardware.camera2.CameraDevice#TEMPLATE_STILL_CAPTURE, android.hardware.camera2.CameraDevice#TEMPLATE_RECORD, android.hardware.camera2.CameraDevice#TEMPLATE_VIDEO_SNAPSHOT, android.hardware.camera2.CameraDevice#TEMPLATE_ZERO_SHUTTER_LAG, or android.hardware.camera2.CameraDevice#TEMPLATE_MANUAL

Parameters
`templateType`	Int: An enumeration selecting the use case for this request. Not all template types are supported on every device. See the documentation for each template type for details. Value is `android.hardware.camera2.CameraDevice#TEMPLATE_PREVIEW`, `android.hardware.camera2.CameraDevice#TEMPLATE_STILL_CAPTURE`, `android.hardware.camera2.CameraDevice#TEMPLATE_RECORD`, `android.hardware.camera2.CameraDevice#TEMPLATE_VIDEO_SNAPSHOT`, `android.hardware.camera2.CameraDevice#TEMPLATE_ZERO_SHUTTER_LAG`, or `android.hardware.camera2.CameraDevice#TEMPLATE_MANUAL`

Return
`CaptureRequest.Builder`	a builder for a capture request, initialized with default settings for that template, and no output streams This value cannot be `null`.

Exceptions
`android.hardware.camera2.CameraAccessException`	if the querying the camera device failed or there has been a fatal error
`java.lang.IllegalArgumentException`	if the templateType is not supported by this device

getId

Added in API level 35

abstract fun getId(): String

Get the ID of this camera device.

This matches the ID given to CameraManager#getCameraDeviceSetup to instantiate this object.

Return
`String`	the ID for this camera device This value cannot be `null`.

See Also

android.hardware.camera2.CameraManager#getCameraIdList

getSessionCharacteristics

Added in API level 35

abstract fun getSessionCharacteristics(sessionConfig: SessionConfiguration): CameraCharacteristics

Get camera characteristics for a particular session configuration for this camera device.

The camera characteristics returned by this method are different from those returned from CameraManager#getCameraCharacteristics. The characteristics returned here reflect device capabilities more accurately if the device were to be configured with sessionConfig. The keys that may get updated are listed in CameraCharacteristics#getAvailableSessionCharacteristicsKeys.

Other than that, the characteristics returned here can be used in the same way as those returned from CameraManager#getCameraCharacteristics.

To optimize latency, the application can call this method before acquiring valid android.view.SurfaceView, android.graphics.SurfaceTexture, android.media.MediaRecorder, android.media.MediaCodec, or surfaces. For android.view.SurfaceView, android.graphics.SurfaceTexture, android.media.MediaRecorder, and android.media.MediaCodec, the application can call OutputConfiguration#OutputConfiguration(Size, Class). For , the application can call android.hardware.camera2.params.OutputConfiguration#OutputConfiguration(int,android.util.Size), android.hardware.camera2.params.OutputConfiguration#OutputConfiguration(int,int,android.util.Size), android.hardware.camera2.params.OutputConfiguration#OutputConfiguration(int,android.util.Size,long), or android.hardware.camera2.params.OutputConfiguration#OutputConfiguration(int,int,android.util.Size,long). The SessionConfiguration can then be created using the OutputConfiguration objects and be used for this function. To create the CameraCaptureSession, the application still needs to make sure all output surfaces are added via android.hardware.camera2.params.OutputConfiguration#addSurface with the exception of deferred surfaces for and android.graphics.SurfaceTexture.

Parameters
`sessionConfig`	SessionConfiguration: The session configuration for which characteristics are fetched. This value cannot be `null`.

Return
`CameraCharacteristics`	CameraCharacteristics specific to a given session configuration. This value cannot be `null`.

Exceptions
`java.lang.IllegalArgumentException`	if the session configuration is invalid or if `isSessionConfigurationSupported` returns `false` for the provided `SessionConfiguration`
`android.hardware.camera2.CameraAccessException`	if the camera device is no longer connected or has encountered a fatal error

See Also

android.hardware.camera2.CameraCharacteristics#getAvailableSessionCharacteristicsKeys

isSessionConfigurationSupported

Added in API level 35

abstract fun isSessionConfigurationSupported(config: SessionConfiguration): Boolean

Checks whether a particular SessionConfiguration is supported by the camera device.

This method performs a runtime check of a given SessionConfiguration. The result confirms whether or not the SessionConfiguration, including the parameters specified via SessionConfiguration#setSessionParameters, can be used to create a camera capture session using CameraDevice#createCaptureSession(SessionConfiguration).

This method is supported if the CameraCharacteristics#INFO_SESSION_CONFIGURATION_QUERY_VERSION is at least android.os.Build.VERSION_CODES#VANILLA_ICE_CREAM. If less or equal to android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, this function throws UnsupportedOperationException.

Although this method is much faster than creating a new capture session, it can still take a few milliseconds per call. Applications should therefore not use this method to explore the entire space of supported session combinations.

Instead, applications should use this method to query whether combinations of certain features are supported. android.hardware.camera2.CameraCharacteristics#INFO_SESSION_CONFIGURATION_QUERY_VERSION provides the list of feature combinations the camera device will reliably report.

IMPORTANT:

If feature support can be queried via CameraCharacteristics#SCALER_MANDATORY_STREAM_COMBINATIONS or CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP, applications should directly use that route rather than calling this function as: (1) using CameraCharacteristics is more efficient, and (2) calling this function with certain non-supported features will throw a IllegalArgumentException.
To minimize SessionConfiguration creation latency due to its dependency on output surfaces, the application can call this method before acquiring valid android.view.SurfaceView, android.graphics.SurfaceTexture, android.media.MediaRecorder, android.media.MediaCodec, or surfaces. For android.view.SurfaceView, android.graphics.SurfaceTexture, android.media.MediaRecorder, and android.media.MediaCodec, the application can call OutputConfiguration#OutputConfiguration(Size, Class). For , the application can call android.hardware.camera2.params.OutputConfiguration#OutputConfiguration(int,android.util.Size), android.hardware.camera2.params.OutputConfiguration#OutputConfiguration(int,int,android.util.Size), android.hardware.camera2.params.OutputConfiguration#OutputConfiguration(int,android.util.Size,long), or android.hardware.camera2.params.OutputConfiguration#OutputConfiguration(int,int,android.util.Size,long). The SessionConfiguration can then be created using the OutputConfiguration objects and be used to query whether it's supported by the camera device. To create the CameraCaptureSession, the application still needs to make sure all output surfaces are added via OutputConfiguration#addSurface with the exception of deferred surfaces for android.view.SurfaceView and android.graphics.SurfaceTexture.

Parameters
`config`	SessionConfiguration: This value cannot be `null`.

Return
`Boolean`	`true` if the given session configuration is supported by the camera device, `false` otherwise.

Exceptions
`android.hardware.camera2.CameraAccessException`	if the camera device is no longer connected or has encountered a fatal error
`java.lang.IllegalArgumentException`	if the session configuration is invalid

See Also

openCamera

Added in API level 35

abstract fun openCamera(
    executor: Executor, 
    callback: CameraDevice.StateCallback
): Unit

Utility function to forward the call to CameraManager#openCamera(String, Executor, StateCallback). This function simply calls CameraManager.openCamera for the cameraId for which this class was constructed. All semantics are consistent with CameraManager.openCamera.
Requires android.Manifest.permission#CAMERA

Parameters

executor Executor: The executor which will be used when invoking the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

callback CameraDevice.StateCallback: The callback which is invoked once the camera is opened This value cannot be null.

Parameters
`executor`	Executor: The executor which will be used when invoking the callback. This value cannot be `null`. Callback and listener events are dispatched through this `Executor`, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use `Context.getMainExecutor()`. Otherwise, provide an `Executor` that dispatches to an appropriate thread.
`callback`	CameraDevice.StateCallback: The callback which is invoked once the camera is opened This value cannot be `null`.

Exceptions
`android.hardware.camera2.CameraAccessException`	if the camera is disabled by device policy, has been disconnected, or is being used by a higher-priority camera API client.
`java.lang.IllegalArgumentException`	if cameraId, the callback or the executor was null, or the cameraId does not match any currently or previously available camera device.
`java.lang.SecurityException`	if the application does not have permission to access the camera

See Also

android.hardware.camera2.CameraManager#openCamera(String, Executor, StateCallback)