public final class

ImageCapture.Builder

extends java.lang.Object

implements UseCaseConfig.Builder<ImageCapture, ImageCaptureConfig, ImageCapture.Builder>, ImageOutputConfig.Builder<ImageCapture.Builder>, IoConfig.Builder<ImageCapture.Builder>, ImageInputConfig.Builder<ImageCapture.Builder>

 java.lang.Object

↳androidx.camera.core.ImageCapture.Builder

Overview

Builder for an ImageCapture.

Summary

Constructors
publicBuilder()

Creates a new Builder object.

Methods
public ImageCapturebuild()

Builds an immutable ImageCapture from the current state.

public static ImageCapture.BuilderfromConfig(Config configuration)

Generates a Builder from another Config object

public MutableConfiggetMutableConfig()

public ImageCaptureConfiggetUseCaseConfig()

public ImageCapture.BuildersetBufferFormat(int bufferImageFormat)

Sets the of the ImageProxy returned by the ImageCapture.OnImageCapturedCallback.

public ImageCapture.BuildersetCaptureMode(int captureMode)

Sets the image capture mode.

public ImageCapture.BuildersetCaptureOptionUnpacker(CaptureConfig.OptionUnpacker optionUnpacker)

public ImageCapture.BuildersetCaptureType(UseCaseConfigFactory.CaptureType captureType)

public ImageCapture.BuildersetCustomOrderedResolutions(java.util.List<Size> resolutions)

public ImageCapture.BuildersetDefaultCaptureConfig(CaptureConfig captureConfig)

public ImageCapture.BuildersetDefaultResolution(Size resolution)

Sets the default resolution of the intended target from this configuration.

public ImageCapture.BuildersetDefaultSessionConfig(SessionConfig sessionConfig)

public ImageCapture.BuildersetDynamicRange(DynamicRange dynamicRange)

Sets the DynamicRange.

public ImageCapture.BuildersetFlashMode(int flashMode)

Sets the flashMode.

public ImageCapture.BuildersetFlashType(int flashType)

Sets the flashType.

public ImageCapture.BuildersetHighResolutionDisabled(boolean disabled)

public ImageCapture.BuildersetImageReaderProxyProvider(ImageReaderProxyProvider imageReaderProxyProvider)

public ImageCapture.BuildersetIoExecutor(java.util.concurrent.Executor executor)

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

public ImageCapture.BuildersetJpegQuality(int jpegQuality)

Sets the output JPEG image compression quality.

public ImageCapture.BuildersetMaxResolution(Size resolution)

public ImageCapture.BuildersetMirrorMode(int mirrorMode)

setMirrorMode is not supported on ImageCapture.

public ImageCapture.BuildersetOutputFormat(int outputFormat)

Sets the output format of the captured image.

public ImageCapture.BuildersetPostviewEnabled(boolean postviewEnabled)

Enables postview image generation.

public ImageCapture.BuildersetPostviewResolutionSelector(ResolutionSelector resolutionSelector)

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

public ImageCapture.BuildersetResolutionSelector(ResolutionSelector resolutionSelector)

Sets the resolution selector to select the preferred supported resolution.

public ImageCapture.BuildersetScreenFlash(ImageCapture.ScreenFlash screenFlash)

Sets the ImageCapture.ScreenFlash instance necessary for screen flash operations.

public ImageCapture.BuildersetSessionOptionUnpacker(SessionConfig.OptionUnpacker optionUnpacker)

public ImageCapture.BuildersetSoftwareJpegEncoderRequested(boolean requestSoftwareJpeg)

public ImageCapture.BuildersetSupportedResolutions(java.util.List<> resolutions)

public ImageCapture.BuildersetSurfaceOccupancyPriority(int priority)

public ImageCapture.BuildersetTargetAspectRatio(int aspectRatio)

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

public ImageCapture.BuildersetTargetClass(java.lang.Class<ImageCapture> targetClass)

public ImageCapture.BuildersetTargetName(java.lang.String targetName)

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

public ImageCapture.BuildersetTargetResolution(Size resolution)

Sets the intended output target resolution.

public ImageCapture.BuildersetTargetRotation(int rotation)

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

public ImageCapture.BuildersetZslDisabled(boolean disabled)

from java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructors

public Builder()

Creates a new Builder object.

Methods

public static ImageCapture.Builder fromConfig(Config configuration)

Generates a Builder from another Config object

Parameters:

configuration: An immutable configuration to pre-populate this builder.

Returns:

The new Builder.

public MutableConfig getMutableConfig()

public ImageCaptureConfig getUseCaseConfig()

public ImageCapture build()

Builds an immutable ImageCapture from the current state.

Returns:

A ImageCapture populated with the current state.

public ImageCapture.Builder setCaptureMode(int captureMode)

Sets the image capture mode.

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

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

Parameters:

captureMode: The requested image capture mode.

Returns:

The current Builder.

public ImageCapture.Builder setFlashMode(int flashMode)

Sets the flashMode.

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

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

See ImageCapture.setFlashMode(int) for more information.

Parameters:

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

Returns:

The current Builder.

public ImageCapture.Builder setScreenFlash(ImageCapture.ScreenFlash screenFlash)

Sets the 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 ImageCapture.Builder.setFlashMode(int) with ImageCapture.FLASH_MODE_SCREEN.

See ImageCapture.setScreenFlash(ImageCapture.ScreenFlash) for more information.

Parameters:

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

Returns:

The current Builder.

public ImageCapture.Builder setBufferFormat(int bufferImageFormat)

Sets the of the ImageProxy returned by the ImageCapture.OnImageCapturedCallback.

Warning. This could lead to an invalid configuration as image format support is per device. Also, setting the buffer format in conjuncture with image capture extensions will result in an invalid configuration. In this case ImageCapture.ImageCapture(ImageCaptureConfig) will throw an java.lang.IllegalArgumentException.

Parameters:

bufferImageFormat: The image format for captured images.

Returns:

The current Builder.

public ImageCapture.Builder setSupportedResolutions(java.util.List<> resolutions)

public ImageCapture.Builder setCustomOrderedResolutions(java.util.List<Size> resolutions)

public ImageCapture.Builder setTargetClass(java.lang.Class<ImageCapture> targetClass)

public ImageCapture.Builder setTargetName(java.lang.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:

targetName: A unique string identifier for the instance of the class being configured.

Returns:

the current Builder.

public ImageCapture.Builder setTargetAspectRatio(int aspectRatio)

Deprecated: use ResolutionSelector with 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 AspectRatio.RATIO_DEFAULT is supplied, resolutions with aspect ratio 4:3 will be considered in higher priority.

Parameters:

aspectRatio: The desired ImageCapture AspectRatio

Returns:

The current Builder.

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

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

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

Returns:

The current Builder.

See also: ImageCapture.setTargetRotation(int)

public ImageCapture.Builder setMirrorMode(int mirrorMode)

setMirrorMode is not supported on ImageCapture.

public ImageCapture.Builder setTargetResolution(Size resolution)

Deprecated: use ResolutionSelector with 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 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 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, ImageCapture.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.

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: The target resolution to choose from supported output sizes list.

Returns:

The current Builder.

public ImageCapture.Builder setDefaultResolution(Size resolution)

Sets the default resolution of the intended target from this configuration.

Parameters:

resolution: The default resolution to choose from supported output sizes list.

Returns:

The current Builder.

public ImageCapture.Builder setMaxResolution(Size resolution)

public ImageCapture.Builder setResolutionSelector(ResolutionSelector resolutionSelector)

Sets the resolution selector to select the preferred supported resolution.

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

Returns:

The current Builder.

public 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, ImageCapture.OnImageCapturedCallback.onPostviewBitmapAvailable(Bitmap) or ImageCapture.OnImageSavedCallback.onPostviewBitmapAvailable(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 ResolutionSelector can also be used to select a specific size via ImageCapture.Builder.setPostviewResolutionSelector(ResolutionSelector).

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

Parameters:

postviewEnabled: whether postview is enabled or not

Returns:

the current Builder.

public ImageCapture.Builder setPostviewResolutionSelector(ResolutionSelector resolutionSelector)

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 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 java.lang.IllegalArgumentException when bindToLifecycle() is invoked.

Returns:

the current Builder.

public ImageCapture.Builder setImageReaderProxyProvider(ImageReaderProxyProvider imageReaderProxyProvider)

public ImageCapture.Builder setSoftwareJpegEncoderRequested(boolean requestSoftwareJpeg)

public ImageCapture.Builder setFlashType(int flashType)

Sets the flashType.

If not set, the flash type will default to ImageCapture.FLASH_TYPE_ONE_SHOT_FLASH.

Parameters:

flashType: The requested flash mode. Value is ImageCapture.FLASH_TYPE_ONE_SHOT_FLASH or ImageCapture.FLASH_TYPE_USE_TORCH_AS_FLASH.

Returns:

The current Builder.

public ImageCapture.Builder setJpegQuality(int jpegQuality)

Sets the output JPEG image compression quality.

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

Parameters:

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

Returns:

The current Builder.

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

Parameters:

executor: The executor which will be used for IO tasks.

Returns:

the current Builder.

public ImageCapture.Builder setDefaultSessionConfig(SessionConfig sessionConfig)

public 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 ImageCaptureCapabilities.getSupportedOutputFormats().

If not set, the output format will default to ImageCapture.OUTPUT_FORMAT_JPEG.

If an Ultra HDR output format is used, a DynamicRange.HDR_UNSPECIFIED_10_BIT will be used as the dynamic range of this use case. Please note that some devices may not be able to support configuring both SDR and HDR use cases at the same time, e.g. use Ultra HDR ImageCapture with a SDR Preview. Configuring concurrent SDR and HDR on these devices will result in an java.lang.IllegalArgumentException to be thrown when invoking bindToLifecycle(). Such device specific constraints can be queried by calling .

Parameters:

outputFormat: The output image format. Value is ImageCapture.OUTPUT_FORMAT_JPEG or ImageCapture.OUTPUT_FORMAT_JPEG_ULTRA_HDR.

Returns:

The current Builder.

See also: ImageCapture.OutputFormat, ImageCaptureCapabilities.getSupportedOutputFormats()

public ImageCapture.Builder setDefaultCaptureConfig(CaptureConfig captureConfig)

public ImageCapture.Builder setSessionOptionUnpacker(SessionConfig.OptionUnpacker optionUnpacker)

public ImageCapture.Builder setCaptureOptionUnpacker(CaptureConfig.OptionUnpacker optionUnpacker)

public ImageCapture.Builder setSurfaceOccupancyPriority(int priority)

public ImageCapture.Builder setZslDisabled(boolean disabled)

public ImageCapture.Builder setHighResolutionDisabled(boolean disabled)

public ImageCapture.Builder setCaptureType(UseCaseConfigFactory.CaptureType captureType)

public ImageCapture.Builder setDynamicRange(DynamicRange dynamicRange)

Sets the DynamicRange.

This is currently only exposed to internally set the dynamic range to SDR.

Returns:

The current Builder.

See also: DynamicRange