ViewPort.Builder


public final class ViewPort.Builder


Builder for ViewPort.

Summary

Public constructors

Builder(@NonNull Rational aspectRatio, int rotation)

Creates ViewPort.Builder with aspect ratio and rotation.

Public methods

@NonNull ViewPort

Builds the ViewPort.

@NonNull ViewPort.Builder
setLayoutDirection(int layoutDirection)

Sets the layout direction of the ViewPort.

@NonNull ViewPort.Builder
setScaleType(int scaleType)

Sets the scale type of the ViewPort.

Public constructors

Builder

Added in 1.0.0
public Builder(@NonNull Rational aspectRatio, int rotation)

Creates ViewPort.Builder with aspect ratio and rotation.

To create a ViewPort that is based on the Preview use case, the aspect ratio should be the dimension of the View and the rotation should be the value of getTargetRotation:

val aspectRatio = Rational(viewFinder.width, viewFinder.height)
val viewport = ViewPort.Builder(aspectRatio, preview.getTargetRotation()).build()

In a scenario where Preview is not used, for example, face detection in ImageAnalysis and taking pictures with ImageCapture when faces are found, the ViewPort should be created with the aspect ratio and rotation of the ImageCapture use case.

All UseCases have a configurable aspect ratio setting that determines the supported sizes for creating the capture session to receive images from the camera. See setAspectRatioStrategy for Preview, ImageCapture, and ImageAnalysis, and setAspectRatio for androidx.camera.video.VideoCapture. This is distinct from the ViewPort 's aspect ratio setting, which is used to calculate output crop rectangles among bound UseCases to ensure that they have the same content.

To obtain the maximum field of view (FOV) of the full camera sensor, it is recommended that the ViewPort and the bound UseCases have matching aspect ratio settings. Otherwise, the output crop rectangles may be a double-cropped result from the full camera sensor FOV.

For example, if all UseCases have a 16:9 aspect ratio preference setting and are bound with a ViewPort with a 4:3 aspect ratio, the images obtained from the camera will be 16:9 images cropped from the 4:3 camera sensor data. The content inside the output crop rectangles will be 4:3 cropped images from the 16:9 images cropped from the 4:3 camera sensor data. In other words, the images will be cropped twice: first to fit the 16:9 aspect ratio, and then to fit the 4:3 aspect ratio. This will result in a loss of FOV. To avoid this, it is important to ensure that the ViewPort and the bound UseCases have matching aspect ratio settings.

Parameters
@NonNull Rational aspectRatio

aspect ratio of the output crop rect if the scale type is FILL_START, FILL_CENTER or FILL_END. This is usually the width/height of the preview viewfinder that displays the camera feed. The value is ignored if the scale type is FIT.

int rotation

The rotation value is one of four valid values: ROTATION_0, ROTATION_90, ROTATION_180, ROTATION_270.

Public methods

build

Added in 1.0.0
public @NonNull ViewPort build()

Builds the ViewPort.

setLayoutDirection

Added in 1.1.0
public @NonNull ViewPort.Builder setLayoutDirection(int layoutDirection)

Sets the layout direction of the ViewPort.

The layout direction decides the start and the end of the crop rect if the scale type is FILL_END or FILL_START.

The default value is LTR if not set.

setScaleType

Added in 1.1.0
public @NonNull ViewPort.Builder setScaleType(int scaleType)

Sets the scale type of the ViewPort.

The value is used by UseCase to calculate the crop rect.

The default value is FILL_CENTER if not set.