# CaptureRequest.Builder
Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
Summary:[Methods](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#pubmethods)\|[Inherited Methods](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#inhmethods)
# CaptureRequest.Builder
*** ** * ** ***
[Kotlin](https://developer.android.com/reference/kotlin/android/hardware/camera2/CaptureRequest.Builder "View this page in Kotlin")\|Java
`
public
static
final
class
CaptureRequest.Builder
`
`
extends `[Object](https://developer.android.com/reference/java/lang/Object)`
``
`
|---|-------------------------------------------------|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.hardware.camera2.CaptureRequest.Builder |
*** ** * ** ***
A builder for capture requests.
To obtain a builder instance, use the[CameraDevice.createCaptureRequest](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createCaptureRequest(int))or[CameraDevice.CameraDeviceSetup.createCaptureRequest](https://developer.android.com/reference/android/hardware/camera2/CameraDevice.CameraDeviceSetup#createCaptureRequest(int))method, which initializes the request fields to one of the templates defined in[CameraDevice](https://developer.android.com/reference/android/hardware/camera2/CameraDevice).
**See also:**
- [CameraDevice.createCaptureRequest(int)](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createCaptureRequest(int))
- [CameraDevice.TEMPLATE_PREVIEW](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#TEMPLATE_PREVIEW)
- [CameraDevice.TEMPLATE_RECORD](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#TEMPLATE_RECORD)
- [CameraDevice.TEMPLATE_STILL_CAPTURE](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#TEMPLATE_STILL_CAPTURE)
- [CameraDevice.TEMPLATE_VIDEO_SNAPSHOT](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#TEMPLATE_VIDEO_SNAPSHOT)
- [CameraDevice.TEMPLATE_MANUAL](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#TEMPLATE_MANUAL)
- [CameraDevice.CameraDeviceSetup.createCaptureRequest(int)](https://developer.android.com/reference/android/hardware/camera2/CameraDevice.CameraDeviceSetup#createCaptureRequest(int))
## Summary
| ### Public methods ||
|--------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` void` | ` `[addTarget](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#addTarget(android.view.Surface))`(`[Surface](https://developer.android.com/reference/android/view/Surface)` outputTarget) `
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](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createCaptureSession(android.hardware.camera2.params.SessionConfiguration)), when the request is given to the camera device. |
| ` `[CaptureRequest](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest) | ` `[build](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#build())`() ` Build a request using the current target Surfaces and settings. |
| ` T` | ` `[get](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#get(android.hardware.camera2.CaptureRequest.Key))`(`[Key](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Key)` key) ` Get a capture request field value. |
| ` T` | ` `[getPhysicalCameraKey](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#getPhysicalCameraKey(android.hardware.camera2.CaptureRequest.Key,%20java.lang.String))`(`[Key](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Key)` key, `[String](https://developer.android.com/reference/java/lang/String)` physicalCameraId) ` Get a capture request field value for a specific physical camera Id. |
| ` void` | ` `[removeTarget](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#removeTarget(android.view.Surface))`(`[Surface](https://developer.android.com/reference/android/view/Surface)` outputTarget) `
Remove a surface from the list of targets for this request. |
| ` void` | ` `[set](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#set(android.hardware.camera2.CaptureRequest.Key,%20T))`(`[Key](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Key)` key, T value) ` Set a capture request field to a value. |
| ` `[CaptureRequest.Builder](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder) | ` `[setPhysicalCameraKey](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#setPhysicalCameraKey(android.hardware.camera2.CaptureRequest.Key,%20T,%20java.lang.String))`(`[Key](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Key)` key, T value, `[String](https://developer.android.com/reference/java/lang/String)` physicalCameraId) ` Set a capture request field to a value. |
| ` void` | ` `[setTag](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder#setTag(java.lang.Object))`(`[Object](https://developer.android.com/reference/java/lang/Object)` tag) ` Set a tag for this request. |
| ### Inherited methods |
|-----------------------|---|
| From class` `[java.lang.Object](https://developer.android.com/reference/java/lang/Object)` ` |--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ` `[Object](https://developer.android.com/reference/java/lang/Object) | ` `[clone](https://developer.android.com/reference/java/lang/Object#clone())`() ` Creates and returns a copy of this object. | | ` boolean` | ` `[equals](https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object))`(`[Object](https://developer.android.com/reference/java/lang/Object)` obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` `[finalize](https://developer.android.com/reference/java/lang/Object#finalize())`() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final `[Class](https://developer.android.com/reference/java/lang/Class)`` | ` `[getClass](https://developer.android.com/reference/java/lang/Object#getClass())`() ` Returns the runtime class of this`Object`. | | ` int` | ` `[hashCode](https://developer.android.com/reference/java/lang/Object#hashCode())`() ` Returns a hash code value for the object. | | ` final void` | ` `[notify](https://developer.android.com/reference/java/lang/Object#notify())`() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` `[notifyAll](https://developer.android.com/reference/java/lang/Object#notifyAll())`() ` Wakes up all threads that are waiting on this object's monitor. | | ` `[String](https://developer.android.com/reference/java/lang/String) | ` `[toString](https://developer.android.com/reference/java/lang/Object#toString())`() ` Returns a string representation of the object. | | ` final void` | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long,%20int))`(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long))`(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait())`() ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*. | ||
## Public methods
### addTarget
Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void addTarget (Surface outputTarget)
```
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](https://developer.android.com/reference/android/hardware/camera2/CameraDevice#createCaptureSession(android.hardware.camera2.params.SessionConfiguration)), when the request is given to the camera device.
Adding a target more than once has no effect.
| Parameters ||
|----------------|---------------------------------------------------------------------------------------------------|
| `outputTarget` | `Surface`: Surface to use as an output target for this request This value cannot be`null`.
|
### build
Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public CaptureRequest build ()
```
Build a request using the current target Surfaces and settings.
Note that, although it is possible to create a`CaptureRequest`with no target[Surface](https://developer.android.com/reference/android/view/Surface)s, passing such a request into[CameraCaptureSession.capture](https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession#capture(android.hardware.camera2.CaptureRequest,%20android.hardware.camera2.CameraCaptureSession.CaptureCallback,%20android.os.Handler)),[CameraCaptureSession.captureBurst](https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession#captureBurst(java.util.List,%20android.hardware.camera2.CameraCaptureSession.CaptureCallback,%20android.os.Handler)),[CameraCaptureSession.setRepeatingBurst](https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession#setRepeatingBurst(java.util.List,%20android.hardware.camera2.CameraCaptureSession.CaptureCallback,%20android.os.Handler)), or[CameraCaptureSession.setRepeatingRequest](https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession#setRepeatingRequest(android.hardware.camera2.CaptureRequest,%20android.hardware.camera2.CameraCaptureSession.CaptureCallback,%20android.os.Handler))will cause that method to throw an[IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException).
| Returns ||
|---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
| [CaptureRequest](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest) | A new capture request instance, ready for submission to the camera device. This value cannot be`null`.
|
### get
Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public T get (Key key)
```
Get a capture request field value. The field definitions can be found in[CaptureRequest](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest).
| Parameters ||
|-------|-------------------------------------------|
| `key` | `Key`: The metadata field to read.
|
| Returns ||
|-----|----------------------------------------------------------------|
| `T` | The value of that key, or`null`if the field is not set.
|
| Throws ||
|--------------------------------------------------------------------------------------------------------|--------------------------|
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException) | if the key was not valid |
### getPhysicalCameraKey
Added in[API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public T getPhysicalCameraKey (Key key,
String physicalCameraId)
```
Get a capture request field value for a specific physical camera Id. The field definitions can be found in[CaptureRequest](https://developer.android.com/reference/android/hardware/camera2/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](https://developer.android.com/reference/android/hardware/camera2/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.
| Parameters ||
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `key` | `Key`: The metadata field to read.
|
| `physicalCameraId` | `String`: A valid physical camera Id. The valid camera Ids can be obtained via calls to[CameraCharacteristics.getPhysicalCameraIds](https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics#getPhysicalCameraIds()). This value cannot be`null`.
|
| Returns ||
|-----|----------------------------------------------------------------|
| `T` | The value of that key, or`null`if the field is not set.
|
| Throws ||
|--------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException) | if the key or physical camera id were not valid |
### removeTarget
Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void removeTarget (Surface outputTarget)
```
Remove a surface from the list of targets for this request.
Removing a target that is not currently added has no effect.
| Parameters ||
|----------------|---------------------------------------------------------------------------------------------------|
| `outputTarget` | `Surface`: Surface to use as an output target for this request This value cannot be`null`.
|
### set
Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void set (Key key,
T value)
```
Set a capture request field to a value. The field definitions can be found in[CaptureRequest](https://developer.android.com/reference/android/hardware/camera2/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.
| Parameters ||
|---------|-----------------------------------------------------------------------------------------|
| `key` | `Key`: The metadata field to write. This value cannot be`null`.
|
| `value` | `T`: The value to set the field to, which must be of a matching type to the key.
|
### setPhysicalCameraKey
Added in[API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public CaptureRequest.Builder setPhysicalCameraKey (Key key,
T value,
String physicalCameraId)
```
Set a capture request field to a value. The field definitions can be found in[CaptureRequest](https://developer.android.com/reference/android/hardware/camera2/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](https://developer.android.com/reference/android/hardware/camera2/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.
| Parameters ||
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `key` | `Key`: The metadata field to write. This value cannot be`null`.
|
| `value` | `T`: The value to set the field to, which must be of a matching type to the key.
|
| `physicalCameraId` | `String`: A valid physical camera Id. The valid camera Ids can be obtained via calls to[CameraCharacteristics.getPhysicalCameraIds](https://developer.android.com/reference/android/hardware/camera2/CameraCharacteristics#getPhysicalCameraIds()). This value cannot be`null`.
|
| Returns ||
|-------------------------------------------------------------------------------------------------------------------|----------------------------|
| [CaptureRequest.Builder](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest.Builder) | The builder object.
|
| Throws ||
|--------------------------------------------------------------------------------------------------------|----------------------------------------|
| [IllegalArgumentException](https://developer.android.com/reference/java/lang/IllegalArgumentException) | if the physical camera id is not valid |
### setTag
Added in[API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public void setTag (Object tag)
```
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](https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.CaptureCallback#onCaptureCompleted(android.hardware.camera2.CameraCaptureSession,%20android.hardware.camera2.CaptureRequest,%20android.hardware.camera2.TotalCaptureResult)).
If the application overrides the tag object's[Object.toString](https://developer.android.com/reference/java/lang/Object#toString())function, the returned string must not contain personal identifiable information.
| Parameters ||
|-------|------------------------------------------------------------------------------------------|
| `tag` | `Object`: an arbitrary Object to store with this request This value may be`null`.
|
**See also:**
- [CaptureRequest.getTag()](https://developer.android.com/reference/android/hardware/camera2/CaptureRequest#getTag())