ResolutionSelector


class ResolutionSelector


A set of requirements and priorities used to select a resolution for the UseCase.

The resolution selection mechanism is determined by the following three steps:

  1. Collect the supported output sizes and add them to the candidate resolution list.
  2. Filter and sort the candidate resolution list according to the Builder resolution settings.
  3. Consider all the resolution selector settings of bound UseCases to find the resolution that best suits each UseCase.

For the first step, all supported resolution output sizes are added to the candidate resolution list as the starting point.

ResolutionSelector provides the following function for applications to adjust the candidate resolution settings.

For the second step, ResolutionSelector provides the following three functions for applications to determine which resolution should be selected with higher priority.

CameraX sorts the collected sizes according to the specified aspect ratio and resolution strategies. The aspect ratio strategy has precedence over the resolution strategy for sorting the resolution candidate list. If applications specify a custom resolution filter, CameraX passes the resulting sizes list, sorted by the specified aspect ratio and resolution strategies, to the resolution filter to get the final desired list.

Different types of UseCases might have their own default settings. You can see the UseCase builders’ setResolutionSelector() function to know the details for each type of UseCase.

In the third step, CameraX selects the final resolution for the UseCase based on the camera device's hardware level, capabilities, and the bound UseCase combination. Applications can check which resolution is finally selected by using the UseCase's getResolutionInfo() function.

Note that a ResolutionSelector with more restricted settings may result in that no resolution can be selected to use. Applications will receive IllegalArgumentException when binding the UseCases with such kind of ResolutionSelector. Applications can specify the AspectRatioStrategy and ResolutionStrategy with proper fallback rules to avoid the IllegalArgumentException or try-catch it and show a proper message to the end users.

When creating a ResolutionSelector instance, the RATIO_4_3_FALLBACK_AUTO_STRATEGY will be the default AspectRatioStrategy if it is not set. PREFER_CAPTURE_RATE_OVER_HIGHER_RESOLUTION is the default allowed resolution mode. However, if neither the ResolutionStrategy nor the ResolutionFilter are set, there will be no default value specified.

Summary

Nested types

Builder for a ResolutionSelector.

Constants

const Int

This mode allows CameraX to select the normal output sizes on the camera device.

const Int

This mode allows CameraX to select the output sizes which might result in slower capture times.

Public functions

Int

Returns the specified allowed resolution mode.

AspectRatioStrategy

Returns the specified AspectRatioStrategy, or RATIO_4_3_FALLBACK_AUTO_STRATEGY if none is specified when creating the ResolutionSelector.

ResolutionFilter?

Returns the specified ResolutionFilter implementation, or null if not specified.

ResolutionStrategy?

Returns the specified ResolutionStrategy, or null if not specified.

Constants

PREFER_CAPTURE_RATE_OVER_HIGHER_RESOLUTION

Added in 1.3.0
const val PREFER_CAPTURE_RATE_OVER_HIGHER_RESOLUTION = 0: Int

This mode allows CameraX to select the normal output sizes on the camera device.

The available resolutions for this mode are obtained from the getOutputSizes method from the stream configuration map obtained with the SCALER_STREAM_CONFIGURATION_MAP camera characteristics.

PREFER_HIGHER_RESOLUTION_OVER_CAPTURE_RATE

Added in 1.3.0
const val PREFER_HIGHER_RESOLUTION_OVER_CAPTURE_RATE = 1: Int

This mode allows CameraX to select the output sizes which might result in slower capture times.

The available resolutions for this mode are obtained from the getOutputSizes and getHighResolutionOutputSizes methods from the stream configuration map obtained with the SCALER_STREAM_CONFIGURATION_MAP camera characteristics. However, please note that using a resolution obtained from the getHighResolutionOutputSizes may result in slower capture times. Please see the javadoc of getHighResolutionOutputSizes for more details.

Since Android 12, some devices might support a maximum resolution sensor pixel mode, which allows them to capture additional ultra high resolutions retrieved from SCALER_STREAM_CONFIGURATION_MAP_MAXIMUM_RESOLUTION . This mode does not allow applications to select those ultra high resolutions.

Public functions

getAllowedResolutionMode

Added in 1.3.0
fun getAllowedResolutionMode(): Int

Returns the specified allowed resolution mode.

getAspectRatioStrategy

Added in 1.3.0
fun getAspectRatioStrategy(): AspectRatioStrategy

Returns the specified AspectRatioStrategy, or RATIO_4_3_FALLBACK_AUTO_STRATEGY if none is specified when creating the ResolutionSelector.

getResolutionFilter

Added in 1.3.0
fun getResolutionFilter(): ResolutionFilter?

Returns the specified ResolutionFilter implementation, or null if not specified.

getResolutionStrategy

Added in 1.3.0
fun getResolutionStrategy(): ResolutionStrategy?

Returns the specified ResolutionStrategy, or null if not specified.