ImageCapture.Builder

class ImageCapture.Builder : ExtendableBuilder


Builder for an ImageCapture.

Summary

Public constructors

Creates a new Builder object.

Public functions

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

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

ImageCapture.Builder
setJpegQuality(jpegQuality: @IntRange(from = 1, to = 100) Int)

Sets the output JPEG image compression quality.

ImageCapture.Builder
setPostviewEnabled(postviewEnabled: Boolean)

Enables postview image generation.

ImageCapture.Builder

Set the ResolutionSelector to select the postview size from the available postview sizes.

ImageCapture.Builder

Sets the resolution selector to select the preferred supported resolution.

ImageCapture.Builder

Sets the ScreenFlash instance necessary for screen flash operations.

ImageCapture.Builder
setTargetAspectRatio(aspectRatio: Int)

This function is deprecated.

use ResolutionSelector with AspectRatioStrategy to specify the preferred aspect ratio settings instead.

ImageCapture.Builder
setTargetName(targetName: String)

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

ImageCapture.Builder

This function is deprecated.

use ResolutionSelector with ResolutionStrategy to specify the preferred resolution settings instead.

ImageCapture.Builder

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

Public constructors

Builder

Added in 1.0.0
Builder()

Creates a new Builder object.

Public functions

build

Added in 1.4.0-alpha04
fun build(): ImageCapture

Builds an immutable ImageCapture from the current state.

Returns
ImageCapture

A ImageCapture populated with the current state.

Throws
java.lang.IllegalArgumentException

if attempting to set both target aspect ratio and target resolution, or attempting to set FLASH_MODE_SCREEN without setting a non-null ScreenFlash instance.

setCaptureMode

Added in 1.0.0
fun setCaptureMode(captureMode: Int): ImageCapture.Builder

Sets the image capture mode.

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

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

Parameters
captureMode: Int

The requested image capture mode.

Returns
ImageCapture.Builder

The current Builder.

setFlashMode

Added in 1.0.0
fun setFlashMode(flashMode: Int): ImageCapture.Builder

Sets the flashMode.

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

If set to FLASH_MODE_SCREEN, a non-null ScreenFlash instance must also be set with setScreenFlash. Otherwise, an IllegalArgumentException will be thrown when build is invoked.

See setFlashMode for more information.

Parameters
flashMode: Int

The requested flash mode. Value is FLASH_MODE_AUTO, FLASH_MODE_ON, FLASH_MODE_SCREEN, or FLASH_MODE_OFF.

Returns
ImageCapture.Builder

The current Builder.

setIoExecutor

Added in 1.0.0
fun setIoExecutor(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 takePicture. 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.

Returns
ImageCapture.Builder

the current Builder.

setJpegQuality

Added in 1.1.0
fun setJpegQuality(jpegQuality: @IntRange(from = 1, to = 100) Int): ImageCapture.Builder

Sets the output JPEG image compression quality.

This is used for the ImageProxy which is returned by takePicture or the output JPEG image which is saved by takePicture. The saved JPEG image might be cropped according to the ViewPort setting or the crop aspect ratio set by setCropAspectRatio. 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 CAPTURE_MODE_MINIMIZE_LATENCY and 100 is used for CAPTURE_MODE_MAXIMIZE_QUALITY.

Parameters
jpegQuality: @IntRange(from = 1, to = 100) Int

The requested output JPEG image compression quality. The value must be in range [1..100] which larger is higher quality.

Returns
ImageCapture.Builder

The current Builder.

Throws
java.lang.IllegalArgumentException

if the input value is not in range [1..100].

setPostviewEnabled

Added in 1.4.0-alpha04
fun setPostviewEnabled(postviewEnabled: Boolean): ImageCapture.Builder

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, onPostviewBitmapAvailable or onPostviewBitmapAvailable 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 ResolutionSelector can also be used to select a specific size via setPostviewResolutionSelector.

You can query the postview capability by invoking getImageCaptureCapabilities. If isPostviewSupported returns false and you still enable the postview, the postview image won't be generated.

Parameters
postviewEnabled: Boolean

whether postview is enabled or not

Returns
ImageCapture.Builder

the current Builder.

setPostviewResolutionSelector

Added in 1.4.0-alpha04
fun setPostviewResolutionSelector(resolutionSelector: ResolutionSelector): ImageCapture.Builder

Set the 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 androidx.camera.core.resolutionselector.ResolutionFilter and set it to the ResolutionSelector to get the list of available sizes and determine which size to use.

If no sizes can be selected using the given ResolutionSelector, it will throw an IllegalArgumentException when bindToLifecycle() is invoked.

Returns
ImageCapture.Builder

the current Builder.

setResolutionSelector

Added in 1.3.0
fun setResolutionSelector(resolutionSelector: ResolutionSelector): ImageCapture.Builder

Sets the resolution selector to select the preferred supported resolution.

The default resolution strategy for ImageCapture is 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 setTargetResolution and setTargetAspectRatio APIs are deprecated and are not compatible with setResolutionSelector. Calling either of these APIs together with setResolutionSelector will result in an IllegalArgumentException being thrown when you attempt to build the ImageCapture instance.

Returns
ImageCapture.Builder

The current Builder.

setScreenFlash

Added in 1.4.0-alpha04
fun setScreenFlash(screenFlash: ImageCapture.ScreenFlash): ImageCapture.Builder

Sets the 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 setFlashMode with FLASH_MODE_SCREEN.

See setScreenFlash for more information.

Parameters
screenFlash: ImageCapture.ScreenFlash

The ScreenFlash to notify caller for the UI side changes required for photo capture with FLASH_MODE_SCREEN.

Returns
ImageCapture.Builder

The current Builder.

setTargetAspectRatio

Added in 1.0.0
Deprecated in 1.3.0
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 and the resulting aspect ratio may not be exactly as requested.

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

Parameters
aspectRatio: Int

The desired ImageCapture AspectRatio

Returns
ImageCapture.Builder

The current Builder.

setTargetName

Added in 1.0.0
fun setTargetName(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.

Returns
ImageCapture.Builder

the current Builder.

setTargetResolution

Added in 1.0.0
Deprecated in 1.3.0
fun setTargetResolution(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 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, setCropAspectRatio 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.

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 android.hardware.camera2.CameraDevice's href="https://developer.android.com/reference/android/hardware/camera2/CameraDevice #regular-capture">Regular capture section.

Parameters
resolution: Size

The target resolution to choose from supported output sizes list.

Returns
ImageCapture.Builder

The current Builder.

setTargetRotation

Added in 1.0.0
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 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: ROTATION_0, ROTATION_90, ROTATION_180, ROTATION_270. Rotation values are relative to the "natural" rotation, ROTATION_0.

In general, it is best to additionally set the target rotation dynamically on the use case. See setTargetRotation for additional documentation.

If not set, the target rotation will default to the value of 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
rotation: Int

The rotation of the intended target.

Returns
ImageCapture.Builder

The current Builder.