ViewPort.Builder

Builder(aspectRatio: Rational, rotation: Int)

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.

fun build(): ViewPort

Builds the ViewPort.

fun setLayoutDirection(layoutDirection: Int): ViewPort.Builder

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.

fun setScaleType(scaleType: Int): ViewPort.Builder

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.