public final class

Preview.Builder

extends java.lang.Object

implements UseCaseConfig.Builder<Preview, PreviewConfig, Preview.Builder>, ImageOutputConfig.Builder<Preview.Builder>, ThreadConfig.Builder<Preview.Builder>

 java.lang.Object

↳androidx.camera.core.Preview.Builder

Overview

Builder for a Preview.

Summary

Constructors
publicBuilder()

Creates a new Builder object.

Methods
public Previewbuild()

Builds an immutable Preview from the current state.

public static Preview.BuilderfromConfig(PreviewConfig configuration)

Generates a Builder from another Config object

public MutableConfiggetMutableConfig()

public PreviewConfiggetUseCaseConfig()

public Preview.BuildersetBackgroundExecutor(java.util.concurrent.Executor executor)

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

public Preview.BuildersetCameraSelector(CameraSelector cameraSelector)

public Preview.BuildersetCaptureOptionUnpacker(CaptureConfig.OptionUnpacker optionUnpacker)

public Preview.BuildersetCaptureProcessor(CaptureProcessor captureProcessor)

Sets the CaptureProcessor.

public Preview.BuildersetDefaultCaptureConfig(CaptureConfig captureConfig)

public Preview.BuildersetDefaultResolution(Size resolution)

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

public Preview.BuildersetDefaultSessionConfig(SessionConfig sessionConfig)

public Preview.BuildersetImageInfoProcessor(ImageInfoProcessor processor)

public Preview.BuildersetIsRgba8888SurfaceRequired(boolean isRgba8888SurfaceRequired)

Sets if the surface requires RGBA8888 format.

public Preview.BuildersetMaxResolution(Size resolution)

public Preview.BuildersetSessionOptionUnpacker(SessionConfig.OptionUnpacker optionUnpacker)

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

public Preview.BuildersetSurfaceOccupancyPriority(int priority)

public Preview.BuildersetTargetAspectRatio(int aspectRatio)

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

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

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

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

public Preview.BuildersetTargetResolution(Size resolution)

Sets the resolution of the intended target from this configuration.

public Preview.BuildersetTargetRotation(int rotation)

Sets the rotation that the intended target resolution is expressed in.

public Preview.BuildersetUseCaseEventCallback(UseCase.EventCallback useCaseEventCallback)

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 Preview.Builder fromConfig(PreviewConfig 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 PreviewConfig getUseCaseConfig()

public Preview build()

Builds an immutable Preview from the current state.

Returns:

A Preview populated with the current state.

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

public Preview.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 an 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 Preview.Builder setTargetAspectRatio(int aspectRatio)

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.

For Preview, the value will be used to calculate the suggested resolution size in SurfaceRequest.getResolution().

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

For the following devices, the aspect ratio will be forced to AspectRatio.RATIO_16_9 regardless of the config. On these devices, the camera HAL produces a preview with a 16:9 aspect ratio regardless of the aspect ratio of the preview surface.

  • SM-J710MN, Samsung Galaxy J7 (2016)
  • SM-T580, Samsung Galaxy Tab A J7 (2016)

Parameters:

aspectRatio: The desired Preview AspectRatio

Returns:

The current Builder.

public Preview.Builder setTargetRotation(int rotation)

Sets the rotation that the intended target resolution is expressed in.

This sets the rotation that is used when specifying a target resolution using Preview.Builder.setTargetResolution(Size), which accepts a resolution at the target orientation.

rotation is one of four valid values: , , , . Rotation values are relative to the "natural" rotation, .

For example a portrait natural device may specify a portrait image target resolution as 480x640, and the same device rotated to and displaying in landscape (i.e. as returned by Display) may set the target rotation to and resolution to 640x480.

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

Note that does not support non-display rotation. If the target rotation is different than the value of Display, should not be used to provide the in SurfaceRequest.provideSurface(Surface, Executor, Consumer)

Parameters:

rotation: The rotation of the intended target.

Returns:

The current Builder.

See also: Preview.Builder.setTargetResolution(Size)

public Preview.Builder setTargetResolution(Size resolution)

Sets the resolution of the intended target from this configuration.

The target resolution attempts to establish a minimum bound for the preview resolution. The actual preview 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.

The maximum available resolution that could be selected for a Preview is limited to be under 1080p. The limitation of 1080p for Preview has considered both performance and quality factors that users can obtain reasonable quality and smooth output stream under 1080p.

If not set, the default selected resolution will be the best size match to the device's screen resolution, or to 1080p (1920x1080), whichever is smaller. Note that due to compatibility reasons, CameraX may select a resolution that is larger than the default screen resolution on certain devices.

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 Regular capture section.

Parameters:

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

Returns:

The current Builder.

public Preview.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 Preview.Builder setMaxResolution(Size resolution)

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

public Preview.Builder setBackgroundExecutor(java.util.concurrent.Executor executor)

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

If not set, the background executor will default to an automatically generated java.util.concurrent.Executor.

Parameters:

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

Returns:

the current Builder.

public Preview.Builder setDefaultSessionConfig(SessionConfig sessionConfig)

public Preview.Builder setDefaultCaptureConfig(CaptureConfig captureConfig)

public Preview.Builder setSessionOptionUnpacker(SessionConfig.OptionUnpacker optionUnpacker)

public Preview.Builder setCaptureOptionUnpacker(CaptureConfig.OptionUnpacker optionUnpacker)

public Preview.Builder setSurfaceOccupancyPriority(int priority)

public Preview.Builder setCameraSelector(CameraSelector cameraSelector)

public Preview.Builder setUseCaseEventCallback(UseCase.EventCallback useCaseEventCallback)

public Preview.Builder setIsRgba8888SurfaceRequired(boolean isRgba8888SurfaceRequired)

Sets if the surface requires RGBA8888 format.

public Preview.Builder setImageInfoProcessor(ImageInfoProcessor processor)

public Preview.Builder setCaptureProcessor(CaptureProcessor captureProcessor)

Sets the CaptureProcessor.

Parameters:

captureProcessor: The requested capture processor for extension.

Returns:

The current Builder.