Join us for ⁠#Android11: The Beta Launch Show on June 3!

Builder

class Builder : Builder<ImageCapture!, ImageCaptureConfig!, ImageCapture.Builder!>, Builder<ImageCapture.Builder!>, Builder<ImageCapture.Builder!>
kotlin.Any
   ↳ androidx.camera.core.ImageCapture.Builder

Builder for an ImageCapture.

Summary

Public constructors

Creates a new Builder object.

Public methods

ImageCapture

Builds an immutable ImageCapture from the current state.

ImageCapture.Builder
setCaptureMode(captureMode: Int)

Sets the image capture mode.

ImageCapture.Builder
setFlashMode(flashMode: Int)

Sets the flashMode.

ImageCapture.Builder
setIoExecutor(@NonNull executor: Executor)

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

ImageCapture.Builder
setTargetAspectRatio(aspectRatio: Int)

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

ImageCapture.Builder
setTargetName(@NonNull targetName: String)

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

ImageCapture.Builder
setTargetResolution(@NonNull resolution: Size)

Sets the intended output target resolution.

ImageCapture.Builder

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

Public constructors

<init>

Builder()

Creates a new Builder object.

Public methods

build

@NonNull fun build(): ImageCapture

Builds an immutable ImageCapture from the current state.

Return
ImageCapture A ImageCapture populated with the current state.
Exceptions
IllegalArgumentException if attempting to set both target aspect ratio and target resolution.

setCaptureMode

@NonNull fun setCaptureMode(captureMode: Int): ImageCapture.Builder

Sets the image capture mode.

Valid capture modes are CaptureMode#CAPTURE_MODE_MINIMIZE_LATENCY, which prioritizes latency over image quality, or CaptureMode#CAPTURE_MODE_MAXIMIZE_QUALITY, which prioritizes image quality over latency.

If not set, the capture mode will default to CaptureMode#CAPTURE_MODE_MINIMIZE_LATENCY.

Parameters
captureMode Int: The requested image capture mode.
Return
ImageCapture.Builder The current Builder.

setFlashMode

@NonNull fun setFlashMode(flashMode: Int): ImageCapture.Builder

Sets the flashMode.

If not set, the flash mode will default to FLASH_MODE_OFF.

See ImageCapture#setFlashMode(int) for more information.

Parameters
flashMode Int: The requested flash mode. Value is FLASH_MODE_AUTO, FLASH_MODE_ON, or FLASH_MODE_OFF.
Return
ImageCapture.Builder The current Builder.

setIoExecutor

@NonNull fun setIoExecutor(@NonNull executor: Executor): ImageCapture.Builder

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 ImageCapture#takePicture(OutputFileOptions, Executor, * ImageCapture.OnImageSavedCallback). If no executor is set, then a default Executor specifically for IO will be used instead.

Parameters
executor Executor: The executor which will be used for IO tasks.
Return
ImageCapture.Builder the current Builder.

setTargetAspectRatio

@NonNull fun setTargetAspectRatio(aspectRatio: Int): ImageCapture.Builder

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.

If not set, resolutions with aspect ratio 4:3 will be considered in higher priority.

Parameters
aspectRatio Int: The desired ImageCapture AspectRatio
Return
ImageCapture.Builder The current Builder.

setTargetName

@NonNull fun setTargetName(@NonNull targetName: String): ImageCapture.Builder

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
targetName String: A unique string identifier for the instance of the class being configured.
Return
ImageCapture.Builder the current Builder.

setTargetResolution

@NonNull fun setTargetResolution(@NonNull resolution: Size): ImageCapture.Builder

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 Size 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 Size should be expressed at the use cases's 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, ImageCapture.Builder#setCropAspectRatio(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 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.

Parameters
resolution Size: The target resolution to choose from supported output sizes list.
Return
ImageCapture.Builder The current Builder.

setTargetRotation

@NonNull fun setTargetRotation(rotation: Int): ImageCapture.Builder

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 ImageInfo#getRotationDegrees() value of the ImageProxy returned by 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: Surface#ROTATION_0, , Surface#ROTATION_180, Surface#ROTATION_270. Rotation values are relative to the "natural" rotation, Surface#ROTATION_0.

In general, it is best to additionally set the target rotation dynamically on the use case. See androidx.camera.core.ImageCapture#setTargetRotation(int) for additional documentation.

If not set, the target rotation will default to the value of android.view.Display#getRotation() of the default display at the time the use case is created.

Parameters
rotation Int: The rotation of the intended target.
Return
ImageCapture.Builder The current Builder.