# ImageCapture.Builder

Artifact: [androidx.camera:camera-core](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/core/ImageCapture.java+class:androidx.camera.core.ImageCapture.Builder) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

*** ** * ** ***


```
public final class ImageCapture.Builder implements ExtendableBuilder
```

<br />

*** ** * ** ***

Builder for an `https://developer.android.com/reference/androidx/camera/core/ImageCapture`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#Builder()()` Creates a new Builder object. |

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#build()()` Builds an immutable `https://developer.android.com/reference/androidx/camera/core/ImageCapture` from the current state. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setCaptureMode(int)(int captureMode)` Sets the image capture mode. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setFlashMode(int)(int flashMode)` Sets the flashMode. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setInterop(androidx.camera.core.InteropConfigurator<androidx.camera.core.ImageCapture.Builder>)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/InteropConfigurator<https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder> configurator )` Applies interoperability configuration to this builder. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setIoExecutor(java.util.concurrent.Executor)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor)` Sets the default executor that will be used for IO tasks. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setJpegQuality(int)(@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 100) int jpegQuality)` Sets the output JPEG image compression quality. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setOutputFormat(int)(int outputFormat)` Sets the output format of the captured image. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setPostviewEnabled(boolean)(boolean postviewEnabled)` Enables postview image generation. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setPostviewResolutionSelector(androidx.camera.core.resolutionselector.ResolutionSelector)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector resolutionSelector )` Set the `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector` to select the postview size from the available postview sizes. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setResolutionSelector(androidx.camera.core.resolutionselector.ResolutionSelector)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector resolutionSelector)` Sets the resolution selector to select the preferred supported resolution. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setScreenFlash(androidx.camera.core.ImageCapture.ScreenFlash)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.ScreenFlash screenFlash)` Sets the `https://developer.android.com/reference/androidx/camera/core/ImageCapture.ScreenFlash` instance necessary for screen flash operations. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `[setTargetAspectRatio](https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setTargetAspectRatio(int))(int aspectRatio)` **This method is deprecated.** use `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector` with `https://developer.android.com/reference/androidx/camera/core/resolutionselector/AspectRatioStrategy` to specify the preferred aspect ratio settings instead. <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setTargetName(java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html targetName)` Sets the name of the target object being configured, used only for debug logging. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `[setTargetResolution](https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setTargetResolution(android.util.Size))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/util/Size.html resolution)` **This method is deprecated.** use `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector` with `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionStrategy` to specify the preferred resolution settings instead. <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setTargetRotation(int)(int rotation)` Sets the rotation of the intended target for images from this configuration. |

| ### Extension functions |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | `https://developer.android.com/reference/androidx/camera/core/Camera2InteropEx.https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#(androidx.camera.core.ImageCapture.Builder).camera2Interop(kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder receiver, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/camera2/interop/ImageCaptureCamera2Interop, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block )` Applies Camera2 options to an `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder`. |

## Public constructors

### Builder

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public Builder()
```

Creates a new Builder object.

## Public methods

### build

```
public @NonNull ImageCapture build()
```

Builds an immutable `https://developer.android.com/reference/androidx/camera/core/ImageCapture` from the current state.

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture` | A `https://developer.android.com/reference/androidx/camera/core/ImageCapture` populated with the current state. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if attempting to set both target aspect ratio and target resolution, or attempting to set `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_SCREEN()` without setting a non-null `https://developer.android.com/reference/androidx/camera/core/ImageCapture.ScreenFlash` instance. |

### setCaptureMode

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public @NonNull ImageCapture.Builder setCaptureMode(int captureMode)
```

Sets the image capture mode.

Valid capture modes are `https://developer.android.com/reference/androidx/camera/core/ImageCapture#CAPTURE_MODE_MINIMIZE_LATENCY()`, which prioritizes latency over image quality, or `https://developer.android.com/reference/androidx/camera/core/ImageCapture#CAPTURE_MODE_MAXIMIZE_QUALITY()`, which prioritizes image quality over latency.

If not set, the capture mode will default to `https://developer.android.com/reference/androidx/camera/core/ImageCapture#CAPTURE_MODE_MINIMIZE_LATENCY()`.

| Parameters |
|---|---|
| `int captureMode` | The requested image capture mode. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

### setFlashMode

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public @NonNull ImageCapture.Builder setFlashMode(int flashMode)
```

Sets the flashMode.

If not set, the flash mode will default to `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_OFF()`.

If set to `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_SCREEN()`, a non-null `https://developer.android.com/reference/androidx/camera/core/ImageCapture.ScreenFlash` instance must also be set with `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setScreenFlash(androidx.camera.core.ImageCapture.ScreenFlash)`. Otherwise, an `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` will be thrown when `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#build()` is invoked.

See `https://developer.android.com/reference/androidx/camera/core/ImageCapture#setFlashMode(int)` for more information.

| Parameters |
|---|---|
| `int flashMode` | The requested flash mode. Value is `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_AUTO()`, `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_ON()`, `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_SCREEN()`, or `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_OFF()`. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

### setInterop

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
public @NonNull ImageCapture.Builder setInterop(
    @NonNull InteropConfigurator<ImageCapture.Builder> configurator
)
```

Applies interoperability configuration to this builder.

To configure Camera2 options, use `Camera2Interop.forImageCapture(configurator)` (from the `camera-camera2` artifact) to create a configurator, then pass it to this method.

**Note:** Using Camera2 interop options can override internal CameraX configurations. The capture request keys for one-shot still captures (e.g. `https://developer.android.com/reference/androidx/camera/core/ImageCapture#takePicture(java.util.concurrent.Executor,androidx.camera.core.ImageCapture.OnImageCapturedCallback)`) are determined by copying all repeating request keys (which may include keys added via `https://developer.android.com/reference/androidx/camera/core/SessionConfig.Builder#setInterop(androidx.camera.core.InteropConfigurator<? super androidx.camera.core.SessionConfig.Builder>)` or `https://developer.android.com/reference/androidx/camera/core/CameraControl#applyInteropAsync(androidx.camera.core.InteropConfigurator<? super androidx.camera.core.CameraControl>)`) and then overriding them with the still capture request keys configured here. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior.

**Warning:** Callbacks configured via interop receive raw `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html` instances. Directly invoking state-altering methods on these raw objects (such as `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#close()` or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#abortCaptures()`) bypasses CameraX pipeline management and may cause state desynchronization, stream interruption, or application crashes.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/InteropConfigurator<https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder> configurator` | the configurator that sets the interoperability options |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | this builder |

### setIoExecutor

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public @NonNull ImageCapture.Builder setIoExecutor(@NonNull Executor executor)
```

Sets the default executor that will be used for IO tasks.

This executor will be used for any IO tasks specifically for ImageCapture, such as `https://developer.android.com/reference/androidx/camera/core/ImageCapture#takePicture(androidx.camera.core.ImageCapture.OutputFileOptions,java.util.concurrent.Executor,androidx.camera.core.ImageCapture.OnImageSavedCallback)`. If no executor is set, then a default Executor specifically for IO will be used instead.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor` | The executor which will be used for IO tasks. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | the current Builder. |

### setJpegQuality

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/camera#1.1.0)

```
public @NonNull ImageCapture.Builder setJpegQuality(@IntRange(from = 1, to = 100) int jpegQuality)
```

Sets the output JPEG image compression quality.

This is used for the `https://developer.android.com/reference/androidx/camera/core/ImageProxy` which is returned by `https://developer.android.com/reference/androidx/camera/core/ImageCapture#takePicture(java.util.concurrent.Executor,androidx.camera.core.ImageCapture.OnImageCapturedCallback)` or the output JPEG image which is saved by `https://developer.android.com/reference/androidx/camera/core/ImageCapture#takePicture(androidx.camera.core.ImageCapture.OutputFileOptions,java.util.concurrent.Executor,androidx.camera.core.ImageCapture.OnImageSavedCallback)`. The saved JPEG image might be cropped according to the `https://developer.android.com/reference/androidx/camera/core/ViewPort` setting or the crop aspect ratio set by `https://developer.android.com/reference/androidx/camera/core/ImageCapture#setCropAspectRatio(android.util.Rational)`. The JPEG quality setting will also be used to compress the cropped output image.

If not set, a default value will be used according to the capture mode setting. JPEG compression quality 95 is used for `https://developer.android.com/reference/androidx/camera/core/ImageCapture#CAPTURE_MODE_MINIMIZE_LATENCY()` and 100 is used for `https://developer.android.com/reference/androidx/camera/core/ImageCapture#CAPTURE_MODE_MAXIMIZE_QUALITY()`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/IntRange(from = 1, to = 100) int jpegQuality` | The requested output JPEG image compression quality. The value must be in range \[1..100\] which larger is higher quality. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if the input value is not in range \[1..100\]. |

### setOutputFormat

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/camera#1.4.0)

```
public @NonNull ImageCapture.Builder setOutputFormat(int outputFormat)
```

Sets the output format of the captured image.

The supported output formats for capturing image depend on the capabilities of the camera. The supported output formats of the camera can be queried using `https://developer.android.com/reference/androidx/camera/core/ImageCaptureCapabilities#getSupportedOutputFormats()`.

If not set, the output format will default to `https://developer.android.com/reference/androidx/camera/core/ImageCapture#OUTPUT_FORMAT_JPEG()`.

An `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` will be thrown when binding the UseCase if the specified output format is not supported. Please note that the supported output formats might be changed when Extensions is enabled.

| Parameters |
|---|---|
| `int outputFormat` | The output image format. Value is `https://developer.android.com/reference/androidx/camera/core/ImageCapture#OUTPUT_FORMAT_JPEG()` or `https://developer.android.com/reference/androidx/camera/core/ImageCapture#OUTPUT_FORMAT_JPEG_ULTRA_HDR()` or `https://developer.android.com/reference/androidx/camera/core/ImageCapture#OUTPUT_FORMAT_RAW()`. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/camera/core/ImageCapture.OutputFormat` |   |
| `https://developer.android.com/reference/androidx/camera/core/ImageCaptureCapabilities#getSupportedOutputFormats()` |   |

### setPostviewEnabled

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/camera#1.4.0)

```
public @NonNull ImageCapture.Builder setPostviewEnabled(boolean postviewEnabled)
```

Enables postview image generation. A postview image is a low-quality image that's produced earlier during image capture than the final high-quality image, and can be used as a thumbnail or placeholder until the final image is ready.

When the postview is available, `https://developer.android.com/reference/androidx/camera/core/ImageCapture.OnImageCapturedCallback#onPostviewBitmapAvailable(android.graphics.Bitmap)` or `https://developer.android.com/reference/androidx/camera/core/ImageCapture.OnImageSavedCallback#onPostviewBitmapAvailable(android.graphics.Bitmap)` will be called.

By default the largest available postview size that is smaller or equal to the ImagaeCapture size will be used to configure the postview. The `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector` can also be used to select a specific size via `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setPostviewResolutionSelector(androidx.camera.core.resolutionselector.ResolutionSelector)`.

You can query the postview capability by invoking `https://developer.android.com/reference/androidx/camera/core/ImageCapture#getImageCaptureCapabilities(androidx.camera.core.CameraInfo)`. If `https://developer.android.com/reference/androidx/camera/core/ImageCaptureCapabilities#isPostviewSupported()` returns false and you still enable the postview, the postview image won't be generated.

| Parameters |
|---|---|
| `boolean postviewEnabled` | whether postview is enabled or not |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | the current Builder. |

### setPostviewResolutionSelector

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/camera#1.4.0)

```
public @NonNull ImageCapture.Builder setPostviewResolutionSelector(
    @NonNull ResolutionSelector resolutionSelector
)
```

Set the `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector` to select the postview size from the available postview sizes. These available postview sizes are smaller or equal to the ImageCapture size. You can implement the `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionFilter` and set it to the `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector` to get the list of available sizes and determine which size to use.

If no sizes can be selected using the given `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector`, it will throw an `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` when `bindToLifecycle()` is invoked.

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | the current Builder. |

### setResolutionSelector

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/camera#1.3.0)

```
public @NonNull ImageCapture.Builder setResolutionSelector(@NonNull ResolutionSelector resolutionSelector)
```

Sets the resolution selector to select the preferred supported resolution.

The default resolution strategy for ImageCapture is `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionStrategy#HIGHEST_AVAILABLE_STRATEGY()`, which will select the largest available resolution to use. Applications can override this default strategy with a different resolution strategy.

The existing `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setTargetResolution(android.util.Size)` and `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setTargetAspectRatio(int)` APIs are deprecated and are not compatible with `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setResolutionSelector(androidx.camera.core.resolutionselector.ResolutionSelector)`. Calling either of these APIs together with `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setResolutionSelector(androidx.camera.core.resolutionselector.ResolutionSelector)` will result in an `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` being thrown when you attempt to build the `https://developer.android.com/reference/androidx/camera/core/ImageCapture` instance.

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

### setScreenFlash

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/camera#1.4.0)

```
public @NonNull ImageCapture.Builder setScreenFlash(@NonNull ImageCapture.ScreenFlash screenFlash)
```

Sets the `https://developer.android.com/reference/androidx/camera/core/ImageCapture.ScreenFlash` instance necessary for screen flash operations.

If not set, the instance will be set to null and users will need to set it later before calling `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setFlashMode(int)` with `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_SCREEN()`.

See `https://developer.android.com/reference/androidx/camera/core/ImageCapture#setScreenFlash(androidx.camera.core.ImageCapture.ScreenFlash)` for more information.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.ScreenFlash screenFlash` | The `https://developer.android.com/reference/androidx/camera/core/ImageCapture.ScreenFlash` to notify caller for the UI side changes required for photo capture with `https://developer.android.com/reference/androidx/camera/core/ImageCapture#FLASH_MODE_SCREEN()`. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

### setTargetAspectRatio

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0) Deprecated in [1.3.0](https://developer.android.com/jetpack/androidx/releases/camera#1.3.0)

```
public @NonNull ImageCapture.Builder [setTargetAspectRatio](https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setTargetAspectRatio(int))(int aspectRatio)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> use `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector` with `https://developer.android.com/reference/androidx/camera/core/resolutionselector/AspectRatioStrategy` to specify the preferred aspect ratio settings instead.

Sets the aspect ratio of the intended target for images from this configuration.

The aspect ratio is the ratio of width to height in the sensor orientation.

It is not allowed to set both target aspect ratio and target resolution on the same use case. Attempting so will throw an IllegalArgumentException when building the Config.

The target aspect ratio is used as a hint when determining the resulting output aspect ratio which may differ from the request, possibly due to device constraints. Application code should check the resulting output's resolution and the resulting aspect ratio may not be exactly as requested.

If not set, or `https://developer.android.com/reference/androidx/camera/core/AspectRatio#RATIO_DEFAULT()` is supplied, resolutions with aspect ratio 4:3 will be considered in higher priority.

| Parameters |
|---|---|
| `int aspectRatio` | The desired ImageCapture `https://developer.android.com/reference/androidx/camera/core/AspectRatio` |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

### setTargetName

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public @NonNull ImageCapture.Builder setTargetName(@NonNull String targetName)
```

Sets the name of the target object being configured, used only for debug logging.

The name should be a value that can uniquely identify an instance of the object being configured.

If not set, the target name will default to a unique name automatically generated with the class canonical name and random UUID.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html targetName` | A unique string identifier for the instance of the class being configured. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | the current Builder. |

### setTargetResolution

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0) Deprecated in [1.3.0](https://developer.android.com/jetpack/androidx/releases/camera#1.3.0)

```
public @NonNull ImageCapture.Builder [setTargetResolution](https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder#setTargetResolution(android.util.Size))(@NonNull Size resolution)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> use `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionSelector` with `https://developer.android.com/reference/androidx/camera/core/resolutionselector/ResolutionStrategy` to specify the preferred resolution settings instead.

Sets the intended output target resolution.

The target resolution attempts to establish a minimum bound for the image resolution. The actual image resolution will be the closest available resolution in size that is not smaller than the target resolution, as determined by the Camera implementation. However, if no resolution exists that is equal to or larger than the target resolution, the nearest available resolution smaller than the target resolution will be chosen. Resolutions with the same aspect ratio of the provided `https://developer.android.com/reference/android/util/Size.html` will be considered in higher priority before resolutions of different aspect ratios.

It is not allowed to set both target aspect ratio and target resolution on the same use case. Attempting so will throw an IllegalArgumentException when building the Config.

The resolution `https://developer.android.com/reference/android/util/Size.html` should be expressed in the coordinate frame after rotating the supported sizes by the target rotation. For example, a device with portrait natural orientation in natural target rotation requesting a portrait image may specify 480x640, and the same device, rotated 90 degrees and targeting landscape orientation may specify 640x480.

When the target resolution is set, `https://developer.android.com/reference/androidx/camera/core/ImageCapture#setCropAspectRatio(android.util.Rational)` will be automatically called to set corresponding value. Such that the output image will be cropped into the desired aspect ratio.

The maximum available resolution that could be selected for an `https://developer.android.com/reference/androidx/camera/core/ImageCapture` will depend on the camera device's capability.

If not set, the largest available resolution will be selected to use. Usually, users will intend to get the largest still image that the camera device can support.

When using the `camera-camera2` CameraX implementation, which resolution will be finally selected will depend on the camera device's hardware level and the bound use cases combination. For more details see the guaranteed supported configurations tables in `https://developer.android.com/reference/android/hardware/camera2/CameraDevice.html`'s href="https://developer.android.com/reference/android/hardware/camera2/CameraDevice #regular-capture"\>Regular capture section.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/util/Size.html resolution` | The target resolution to choose from supported output sizes list. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

### setTargetRotation

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
public @NonNull ImageCapture.Builder setTargetRotation(int rotation)
```

Sets the rotation of the intended target for images from this configuration.

This will affect the EXIF rotation metadata in images saved by takePicture calls and the `https://developer.android.com/reference/androidx/camera/core/ImageInfo#getRotationDegrees()` value of the `https://developer.android.com/reference/androidx/camera/core/ImageProxy` returned by `https://developer.android.com/reference/androidx/camera/core/ImageCapture.OnImageCapturedCallback`. These will be set to be the rotation, which if applied to the output image data, will make the image match the target rotation specified here.

This is one of four valid values: `https://developer.android.com/reference/android/view/Surface.html#ROTATION_0`, `https://developer.android.com/reference/android/view/Surface.html#ROTATION_90`, `https://developer.android.com/reference/android/view/Surface.html#ROTATION_180`, `https://developer.android.com/reference/android/view/Surface.html#ROTATION_270`. Rotation values are relative to the "natural" rotation, `https://developer.android.com/reference/android/view/Surface.html#ROTATION_0`.

In general, it is best to additionally set the target rotation dynamically on the use case. See `https://developer.android.com/reference/androidx/camera/core/ImageCapture#setTargetRotation(int)` for additional documentation.

If not set, the target rotation will default to the value of `https://developer.android.com/reference/android/view/Display.html#getRotation()` of the default display at the time the use case is created. The use case is fully created once it has been attached to a camera.

| Parameters |
|---|---|
| `int rotation` | The rotation of the intended target. Value is one of the following: - `Surface.ROTATION_0` - `Surface.ROTATION_90` - `Surface.ROTATION_180` - `Surface.ROTATION_270` <br /> |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | The current Builder. |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/camera/core/ImageCapture#setTargetRotation(int)` |   |
| `https://developer.android.com/reference/android/view/OrientationEventListener.html` |   |

## Extension functions

### Camera2InteropEx.camera2Interop

Artifact: [androidx.camera:camera-camera2](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/camera2/interop/Camera2InteropEx.kt+function:camera2Interop)

```
public final @NonNull ImageCapture.Builder Camera2InteropEx.camera2Interop(
    @NonNull ImageCapture.Builder receiver,
    @NonNull Function1<@NonNull ImageCaptureCamera2Interop, Unit> block
)
```

Applies Camera2 options to an `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder`.

Configures Camera2 options specific to `https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder`.

Options configured via `https://developer.android.com/reference/androidx/camera/camera2/interop/ImageCaptureCamera2Interop` include:

- Physical camera ID (`https://developer.android.com/reference/androidx/camera/camera2/interop/OutputConfigurationInterop#physicalCameraId()`)

- Stream use case (`https://developer.android.com/reference/androidx/camera/camera2/interop/OutputConfigurationInterop#streamUseCase()`)

- Mirror mode (`https://developer.android.com/reference/androidx/camera/camera2/interop/OutputConfigurationInterop#mirrorMode()`)

- Timestamp base (`https://developer.android.com/reference/androidx/camera/camera2/interop/OutputConfigurationInterop#timestampBase()`)

- Dynamic range profile (`https://developer.android.com/reference/androidx/camera/camera2/interop/OutputConfigurationInterop#dynamicRangeProfile()`)

- Surface group ID (`https://developer.android.com/reference/androidx/camera/camera2/interop/OutputConfigurationInterop#surfaceGroupId()`)

- Still capture request key-value pairs (`https://developer.android.com/reference/androidx/camera/camera2/interop/StillCaptureInterop#stillCaptureRequest()` via `stillCaptureRequest[...]` or `https://developer.android.com/reference/androidx/camera/camera2/interop/StillCaptureInterop#setStillCaptureRequestOption(android.hardware.camera2.CaptureRequest.Key,kotlin.Any)`)

- Still capture request template type (`https://developer.android.com/reference/androidx/camera/camera2/interop/StillCaptureInterop#stillCaptureRequestTemplateType()`)

- Still capture callbacks (`https://developer.android.com/reference/androidx/camera/camera2/interop/StillCaptureInterop#setStillCaptureCallback(java.util.concurrent.Executor,android.hardware.camera2.CameraCaptureSession.CaptureCallback)` or `https://developer.android.com/reference/androidx/camera/camera2/interop/StillCaptureInterop#stillCaptureCallback()`)

**Note:** Using Camera2 interop options can override internal CameraX configurations. The capture request keys for one-shot still captures (such as `https://developer.android.com/reference/androidx/camera/core/ImageCapture#takePicture(java.util.concurrent.Executor,androidx.camera.core.ImageCapture.OnImageCapturedCallback)`) are determined by copying all repeating request keys (which may include keys added via `https://developer.android.com/reference/androidx/camera/core/SessionConfig.Builder#setInterop(androidx.camera.core.InteropConfigurator)` or `https://developer.android.com/reference/androidx/camera/core/CameraControl#applyInteropAsync(androidx.camera.core.InteropConfigurator<? super androidx.camera.core.CameraControl>)`) and then overriding them with the still capture request keys configured here. If an option configured via interop conflicts with options required by CameraX internally, the option from Camera2Interop will override, which may result in unexpected behavior.

**Warning:** Callbacks configured via interop receive raw `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html` instances. Directly invoking state-altering, lifecycle, or request-submitting methods on these raw objects bypasses CameraX pipeline management and causes state desynchronization, stream freezing, or crashes. Do not invoke:

- Session lifecycle methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#close()`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#abortCaptures()`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#stopRepeating()`

- Request submission methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#setRepeatingRequest(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#setRepeatingBurst(java.util.List&lt;android.hardware.camera2.CaptureRequest&gt;, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#capture(android.hardware.camera2.CaptureRequest, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#captureBurst(java.util.List&lt;android.hardware.camera2.CaptureRequest&gt;, android.hardware.camera2.CameraCaptureSession.CaptureCallback, android.os.Handler)`

- Surface / output configuration methods: `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#updateOutputConfiguration(android.hardware.camera2.params.OutputConfiguration)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#finalizeOutputConfigurations(java.util.List&lt;android.hardware.camera2.params.OutputConfiguration&gt;)`, `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#prepare(android.view.Surface)`, or `https://developer.android.com/reference/android/hardware/camera2/CameraCaptureSession.html#switchToOffline(java.util.Collection&lt;android.view.Surface&gt;, java.util.concurrent.Executor, android.hardware.camera2.CameraOfflineSession.CameraOfflineSessionCallback)`

```kotlin
import androidx.camera.camera2.interop.camera2Interop
import androidx.camera.core.ImageCapture
import androidx.camera.core.imageCapture

val imageCapture =
    ImageCapture.Builder()
        .camera2Interop {
            stillCaptureRequestTemplateType = CameraDevice.TEMPLATE_STILL_CAPTURE
            stillCaptureRequest[CaptureRequest.CONTROL_AF_MODE] =
                CaptureRequest.CONTROL_AF_MODE_OFF
            stillCaptureCallback =
                object : CameraCaptureSession.CaptureCallback() {
                    override fun onCaptureCompleted(
                        session: CameraCaptureSession,
                        request: CaptureRequest,
                        result: TotalCaptureResult,
                    ) {}
                }
            physicalCameraId = "5"
        }
        .build()
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/camera2/interop/ImageCaptureCamera2Interop, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block` | configuration block setting Camera2 options on `https://developer.android.com/reference/androidx/camera/camera2/interop/ImageCaptureCamera2Interop` |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/camera/core/ImageCapture.Builder` | this builder |