CameraXConfig

@RequiresApi(value = 21)
public final class CameraXConfig


A configuration for adding implementation and user-specific behavior to CameraX.

CameraXConfig provides customizable options for camera provider instances that persist for the lifetime of the provider.

An implementation of CameraXConfig can be provided by subclassing the Application object and implementing CameraXConfig.Provider. Alternatively, other methods configuration exist such as configureInstance. Examples of how this is used can be found in the androidx.camera.lifecycle package.

Applications can create and use the implementation of CameraXConfig provided in androidx.camera.camera2.

Summary

Nested types

public final class CameraXConfig.Builder

A builder for generating CameraXConfig objects.

public interface CameraXConfig.Provider

An interface which can be implemented to provide the configuration for CameraX.

Public methods

boolean

Returns whether this configuration contains the supplied option.

void
findOptions(
    @NonNull String idSearchString,
    @NonNull Config.OptionMatcher matcher
)

Search the configuration for Options whose id match the supplied search string.

@Nullable CameraSelector

Returns the CameraSelector used to determine the available cameras.

@Nullable Executor

Returns the camera executor which CameraX will use to drive the camera stack.

long

Returns the camera open retry maximum timeout in milliseconds when in active resuming mode.

int

Returns the minimum logging level to be used for CameraX logs.

@NonNull Config.OptionPriority

Returns the current priority of the value for the specified option.

@NonNull Set<Config.OptionPriority>

Returns a Set of all priorities set for the specified option.

@Nullable Handler

Returns the scheduling handler that CameraX will use internally for scheduling future tasks.

@NonNull Class<T>

Retrieves the class of the object being configured.

@Nullable Class<T>
getTargetClass(@Nullable Class<T> valueIfMissing)

Retrieves the class of the object being configured.

@NonNull String

Retrieves the name of the target object being configured.

@Nullable String
getTargetName(@Nullable String valueIfMissing)

Retrieves the name of the target object being configured.

static boolean
hasConflict(
    @NonNull Config.OptionPriority priority1,
    @NonNull Config.OptionPriority priority2
)

Returns if values with these OptionPriority conflict or not.

@NonNull Set<Config.Option<Object>>

Lists all options contained within this configuration.

static @NonNull Config
mergeConfigs(@Nullable Config extendedConfig, @Nullable Config baseConfig)

Merges two configs.

static void
mergeOptionValue(
    @NonNull MutableOptionsBundle mergedConfig,
    @NonNull Config baseConfig,
    @NonNull Config extendedConfig,
    @NonNull Config.Option<Object> opt
)

Merges a specific option value from two configs.

@Nullable ValueT
<ValueT> retrieveOption(@NonNull Config.Option<ValueT> id)

Retrieves the value for the specified option if it exists in the configuration.

abstract @Nullable ValueT
<ValueT> retrieveOption(
    @NonNull Config.Option<ValueT> id,
    @Nullable ValueT valueIfMissing
)

Retrieves the value for the specified option if it exists in the configuration.

@Nullable ValueT
<ValueT> retrieveOption(
    @NonNull Config.Option<ValueT> id,
    @Nullable ValueT valueIfMissing
)

Retrieves the value for the specified option if it exists in the configuration.

@Nullable ValueT
<ValueT> retrieveOptionWithPriority(
    @NonNull Config.Option<ValueT> id,
    @NonNull Config.OptionPriority priority
)

Retrieves the value for the specified option and specified priority if it exists in the configuration.

Public methods

containsOption

public boolean containsOption(@NonNull Config.Option<Object> id)

Returns whether this configuration contains the supplied option.

Parameters
@NonNull Config.Option<Object> id

The Option to search for in this configuration.

Returns
boolean

true if this configuration contains the supplied option; false otherwise.

findOptions

public void findOptions(
    @NonNull String idSearchString,
    @NonNull Config.OptionMatcher matcher
)

Search the configuration for Options whose id match the supplied search string.

Parameters
@NonNull String idSearchString

The id string to search for. This could be a fully qualified id such as \"camerax.core.example.option\" or the stem for an option such as \"camerax.core.example\".

@NonNull Config.OptionMatcher matcher

A callback used to receive results of the search. Results will be sent to onOptionMatched in the order in which they are found inside this configuration. Subsequent results will continue to be sent as long as onOptionMatched returns true.

getAvailableCamerasLimiter

Added in 1.1.0
public @Nullable CameraSelector getAvailableCamerasLimiter(@Nullable CameraSelector valueIfMissing)

Returns the CameraSelector used to determine the available cameras.

getCameraExecutor

Added in 1.1.0
public @Nullable Executor getCameraExecutor(@Nullable Executor valueIfMissing)

Returns the camera executor which CameraX will use to drive the camera stack.

getCameraOpenRetryMaxTimeoutInMillisWhileResuming

Added in 1.4.0-alpha04
public long getCameraOpenRetryMaxTimeoutInMillisWhileResuming()

Returns the camera open retry maximum timeout in milliseconds when in active resuming mode.

If this value is not set, -1L will be returned by default.

getMinimumLoggingLevel

Added in 1.0.0
public int getMinimumLoggingLevel()

Returns the minimum logging level to be used for CameraX logs.

getOptionPriority

public @NonNull Config.OptionPriority getOptionPriority(@NonNull Config.Option<Object> opt)

Returns the current priority of the value for the specified option.

If there are multiple values of various priorities for the specified options, the highest priority will be returned. If the option does not exist, an IllegalArgumentException will be thrown.

getPriorities

public @NonNull Set<Config.OptionPrioritygetPriorities(@NonNull Config.Option<Object> option)

Returns a Set of all priorities set for the specified option.

getSchedulerHandler

Added in 1.1.0
public @Nullable Handler getSchedulerHandler(@Nullable Handler valueIfMissing)

Returns the scheduling handler that CameraX will use internally for scheduling future tasks.

getTargetClass

public @NonNull Class<T> getTargetClass()

Retrieves the class of the object being configured.

Returns
@NonNull Class<T>

The stored value, if it exists in this configuration.

Throws
java.lang.IllegalArgumentException

if the option does not exist in this configuration.

getTargetClass

public @Nullable Class<T> getTargetClass(@Nullable Class<T> valueIfMissing)

Retrieves the class of the object being configured.

Parameters
@Nullable Class<T> valueIfMissing

The value to return if this configuration option has not been set.

Returns
@Nullable Class<T>

The stored value or valueIfMissing if the value does not exist in this configuration.

getTargetName

public @NonNull String getTargetName()

Retrieves the name of the target object being configured.

The name should be a value that can uniquely identify an instance of the object being configured.

Returns
@NonNull String

The stored value, if it exists in this configuration.

Throws
java.lang.IllegalArgumentException

if the option does not exist in this configuration.

getTargetName

public @Nullable String getTargetName(@Nullable String valueIfMissing)

Retrieves the name of the target object being configured.

The name should be a value that can uniquely identify an instance of the object being configured.

Parameters
@Nullable String valueIfMissing

The value to return if this configuration option has not been set.

Returns
@Nullable String

The stored value or valueIfMissing if the value does not exist in this configuration.

hasConflict

public static boolean hasConflict(
    @NonNull Config.OptionPriority priority1,
    @NonNull Config.OptionPriority priority2
)

Returns if values with these OptionPriority conflict or not.

Currently it is not allowed the same option to have different values with priority REQUIRED.

listOptions

public @NonNull Set<Config.Option<Object>> listOptions()

Lists all options contained within this configuration.

Returns
@NonNull Set<Config.Option<Object>>

A Set of Options contained within this configuration.

mergeConfigs

public static @NonNull Config mergeConfigs(@Nullable Config extendedConfig, @Nullable Config baseConfig)

Merges two configs.

Parameters
@Nullable Config extendedConfig

the extended config. The options in the extendedConfig will be applied on top of the baseConfig based on the option priorities.

@Nullable Config baseConfig

the base config.

Returns
@NonNull Config

a MutableOptionsBundle of the merged config.

mergeOptionValue

public static void mergeOptionValue(
    @NonNull MutableOptionsBundle mergedConfig,
    @NonNull Config baseConfig,
    @NonNull Config extendedConfig,
    @NonNull Config.Option<Object> opt
)

Merges a specific option value from two configs.

Parameters
@NonNull MutableOptionsBundle mergedConfig

the final output config.

@NonNull Config baseConfig

the base config contains the option value which might be overridden by the corresponding option value in the extend config.

@NonNull Config extendedConfig

the extended config contains the option value which might override the corresponding option value in the base config.

@NonNull Config.Option<Object> opt

the option to merge.

retrieveOption

public @Nullable ValueT <ValueT> retrieveOption(@NonNull Config.Option<ValueT> id)

Retrieves the value for the specified option if it exists in the configuration.

If the option does not exist, an exception will be thrown. If there are multiple values being set with multiple OptionPriority, it will return the value of highest priority.

Parameters
<ValueT>

The type for the value associated with the supplied Option.

@NonNull Config.Option<ValueT> id

The Option to search for in this configuration.

Returns
@Nullable ValueT

The value stored in this configuration.

Throws
java.lang.IllegalArgumentException

if the given option does not exist in this configuration.

retrieveOption

public abstract @Nullable ValueT <ValueT> retrieveOption(
    @NonNull Config.Option<ValueT> id,
    @Nullable ValueT valueIfMissing
)

Retrieves the value for the specified option if it exists in the configuration.

If the option does not exist, valueIfMissing will be returned. If there are multiple values being set with multiple OptionPriority, it will return the value of highest priority.

Parameters
<ValueT>

The type for the value associated with the supplied Option.

@NonNull Config.Option<ValueT> id

The Option to search for in this configuration.

@Nullable ValueT valueIfMissing

The value to return if the specified Option does not exist in this configuration.

Returns
@Nullable ValueT

The value stored in this configuration, or valueIfMissing if it does not exist.

retrieveOption

public @Nullable ValueT <ValueT> retrieveOption(
    @NonNull Config.Option<ValueT> id,
    @Nullable ValueT valueIfMissing
)

Retrieves the value for the specified option if it exists in the configuration.

If the option does not exist, valueIfMissing will be returned. If there are multiple values being set with multiple OptionPriority, it will return the value of highest priority.

Parameters
<ValueT>

The type for the value associated with the supplied Option.

@NonNull Config.Option<ValueT> id

The Option to search for in this configuration.

@Nullable ValueT valueIfMissing

The value to return if the specified Option does not exist in this configuration.

Returns
@Nullable ValueT

The value stored in this configuration, or valueIfMissing if it does not exist.

retrieveOptionWithPriority

public @Nullable ValueT <ValueT> retrieveOptionWithPriority(
    @NonNull Config.Option<ValueT> id,
    @NonNull Config.OptionPriority priority
)

Retrieves the value for the specified option and specified priority if it exists in the configuration.

If the option does not exist, an exception will be thrown.

Parameters
<ValueT>

The type for the value associated with the supplied Option.

@NonNull Config.Option<ValueT> id

The Option to search for in this configuration.

Throws
java.lang.IllegalArgumentException

if the given option with specified priority does not exist in this configuration.