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.

• setAllowedResolutionMode

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

• setAspectRatioStrategy
• setResolutionStrategy
• setResolutionFilter

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

const val PREFER_CAPTURE_RATE_OVER_HIGHER_RESOLUTION = 0: Int

const val PREFER_HIGHER_RESOLUTION_OVER_CAPTURE_RATE = 1: Int

fun getAllowedResolutionMode(): Int

fun getAspectRatioStrategy(): AspectRatioStrategy

fun getResolutionFilter(): ResolutionFilter?

fun getResolutionStrategy(): ResolutionStrategy?