Builder

class Builder
kotlin.Any
   ↳ android.hardware.camera2.CaptureRequest.Builder

A builder for capture requests.

To obtain a builder instance, use the CameraDevice#createCaptureRequest method, which initializes the request fields to one of the templates defined in CameraDevice.
Requires API level 21 (Android 5.0, Lollipop)

Summary

Public methods
CaptureRequest.Builder!
setPhysicalCameraKey(key: CaptureRequest.Key<T>, value: T, physicalCameraId: String)

Set a capture request field to a value.

T?
getPhysicalCameraKey(key: CaptureRequest.Key<T>!, physicalCameraId: String)

Get a capture request field value for a specific physical camera Id.

Unit
addTarget(outputTarget: Surface)

Add a surface to the list of targets for this request

Unit
setTag(tag: Any?)

Set a tag for this request.

Unit
removeTarget(outputTarget: Surface)

Remove a surface from the list of targets for this request.

T?

Get a capture request field value.

Unit
set(key: CaptureRequest.Key<T>, value: T)

Set a capture request field to a value.

CaptureRequest

Build a request using the current target Surfaces and settings.

Public methods

setPhysicalCameraKey

added in API level 28
fun <T : Any!> setPhysicalCameraKey(key: CaptureRequest.Key<T>, value: T, physicalCameraId: String): CaptureRequest.Builder!

Set a capture request field to a value. The field definitions can be found in CaptureRequest.

Setting a field to null will remove that field from the capture request. Unless the field is optional, removing it will likely produce an error from the camera device when the request is submitted.

This method can be called for logical camera devices, which are devices that have REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA capability and calls to CameraCharacteristics#getPhysicalCameraIds return a non-empty set of physical devices that are backing the logical camera. The camera Id included in the 'physicalCameraId' argument selects an individual physical device that will receive the customized capture request field.


Requires API level 28 (Android 8.+, P)
Parameters
key CaptureRequest.Key<T>: The metadata field to write. This value must never be null.
value CaptureRequest.Key<T>: The value to set the field to, which must be of a matching
physicalCameraId CaptureRequest.Key<T>: A valid physical camera Id. The valid camera Ids can be obtained via calls to CameraCharacteristics#getPhysicalCameraIds. This value must never be null.
Return
CaptureRequest.Builder!: The builder object. type to the key.
Exceptions
IllegalArgumentException if the physical camera id is not valid

getPhysicalCameraKey

added in API level 28
fun <T : Any!> getPhysicalCameraKey(key: CaptureRequest.Key<T>!, physicalCameraId: String): T?

Get a capture request field value for a specific physical camera Id. The field definitions can be found in CaptureRequest.

This method can be called for logical camera devices, which are devices that have REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA capability and calls to CameraCharacteristics#getPhysicalCameraIds return a non-empty list of physical devices that are backing the logical camera. The camera Id included in the 'physicalCameraId' argument selects an individual physical device and returns its specific capture request field.


Requires API level 28 (Android 8.+, P)
Parameters
key CaptureRequest.Key<T>!: The metadata field to read.
physicalCameraId CaptureRequest.Key<T>!: A valid physical camera Id. The valid camera Ids can be obtained via calls to CameraCharacteristics#getPhysicalCameraIds. This value must never be null.
Return
T?: The value of that key, or null if the field is not set.
Exceptions
IllegalArgumentException if the key or physical camera id were not valid

addTarget

added in API level 21
fun addTarget(outputTarget: Surface): Unit

Add a surface to the list of targets for this request

The Surface added must be one of the surfaces included in the most recent call to CameraDevice#createCaptureSession, when the request is given to the camera device.

Adding a target more than once has no effect.


Requires API level 21 (Android 5.0, Lollipop)
Parameters
outputTarget Surface: Surface to use as an output target for this request This value must never be null.

setTag

added in API level 21
fun setTag(tag: Any?): Unit

Set a tag for this request.

This tag is not used for anything by the camera device, but can be used by an application to easily identify a CaptureRequest when it is returned by CaptureCallback.onCaptureCompleted
Requires API level 21 (Android 5.0, Lollipop)

Parameters
tag Any?: an arbitrary Object to store with this request This value may be null.

removeTarget

added in API level 21
fun removeTarget(outputTarget: Surface): Unit

Remove a surface from the list of targets for this request.

Removing a target that is not currently added has no effect.


Requires API level 21 (Android 5.0, Lollipop)
Parameters
outputTarget Surface: Surface to use as an output target for this request This value must never be null.

get

added in API level 21
fun <T : Any!> get(key: CaptureRequest.Key<T>!): T?

Get a capture request field value. The field definitions can be found in CaptureRequest.
Requires API level 21 (Android 5.0, Lollipop)

Parameters
key CaptureRequest.Key<T>!: The metadata field to read.
Return
T?: The value of that key, or null if the field is not set.
Exceptions
IllegalArgumentException if the key was not valid

set

added in API level 21
fun <T : Any!> set(key: CaptureRequest.Key<T>, value: T): Unit

Set a capture request field to a value. The field definitions can be found in CaptureRequest.

Setting a field to null will remove that field from the capture request. Unless the field is optional, removing it will likely produce an error from the camera device when the request is submitted.


Requires API level 21 (Android 5.0, Lollipop)
Parameters
key CaptureRequest.Key<T>: The metadata field to write. This value must never be null.
value CaptureRequest.Key<T>: The value to set the field to, which must be of a matching type to the key.

build

added in API level 21
fun build(): CaptureRequest

Build a request using the current target Surfaces and settings.

Note that, although it is possible to create a CaptureRequest with no target Surfaces, passing such a request into CameraCaptureSession#capture, CameraCaptureSession#captureBurst, CameraCaptureSession#setRepeatingBurst, or CameraCaptureSession#setRepeatingRequest will cause that method to throw an IllegalArgumentException.


Requires API level 21 (Android 5.0, Lollipop)
Return
CaptureRequest: A new capture request instance, ready for submission to the camera device. This value will never be null.