xref: /camera/camera-core/src/main/java/androidx/camera/core/impl/Config.java

/*
 * Copyright 2019 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.camera.core.impl;

import androidx.camera.core.impl.utils.ResolutionSelectorUtil;
import androidx.camera.core.resolutionselector.ResolutionSelector;

import com.google.auto.value.AutoValue;

import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;

import java.util.Objects;
import java.util.Set;

/**
 * A Config is a collection of options and values.
 *
 * <p>Config object hold pairs of Options/Values and offer methods for querying whether
 * Options are contained in the configuration along with methods for retrieving the associated
 * values for options.
 *
 * <p>Config allows different values to be set with different {@link OptionPriority} on the same
 * Option. While {@link Config#retrieveOption} will return the option value of the highest priority,
 * {@link Config#retrieveOptionWithPriority} and {@link Config#getPriorities} can be used to
 * retrieve option value of specified priority.
 */
public interface Config {

    /**
     * Returns whether this configuration contains the supplied option.
     *
     * @param id The {@link Option} to search for in this configuration.
     * @return {@code true} if this configuration contains the supplied option; {@code false}
     * otherwise.
     */
    boolean containsOption(@NonNull Option<?> id);

    /**
     * Retrieves the value for the specified option if it exists in the configuration.
     *
     * <p>If the option does not exist, an exception will be thrown. If there are multiple values
     * being set with multiple {@link OptionPriority}, it will return the value of highest
     * priority.
     *
     * @param id       The {@link Option} to search for in this configuration.
     * @param <ValueT> The type for the value associated with the supplied {@link Option}.
     * @return The value stored in this configuration.
     * @throws IllegalArgumentException if the given option does not exist in this configuration.
     */
    <ValueT> @Nullable ValueT retrieveOption(@NonNull Option<ValueT> id);

    /**
     * Retrieves the value for the specified option if it exists in the configuration.
     *
     * <p>If the option does not exist, <code>valueIfMissing</code> will be returned. If there are
     * multiple values being set with multiple {@link OptionPriority}, it will return the value of
     * highest priority.
     *
     * @param id             The {@link Option} to search for in this configuration.
     * @param valueIfMissing The value to return if the specified {@link Option} does not exist in
     *                       this configuration.
     * @param <ValueT>       The type for the value associated with the supplied {@link Option}.
     * @return The value stored in this configuration, or {@code valueIfMissing} if it does
     * not exist.
     */
    <ValueT> @Nullable ValueT retrieveOption(@NonNull Option<ValueT> id,
            @Nullable ValueT valueIfMissing);

    /**
     * Retrieves the value for the specified option and specified priority if it exists in the
     * configuration.
     *
     * <p>If the option does not exist, an exception will be thrown.
     *
     * @param id             The {@link Option} to search for in this configuration.
     * @param <ValueT>       The type for the value associated with the supplied {@link Option}.
     * @throws IllegalArgumentException if the given option with specified priority does not exist
     * in this configuration.
     */
    <ValueT> @Nullable ValueT retrieveOptionWithPriority(@NonNull Option<ValueT> id,
            @NonNull OptionPriority priority);

    /**
     * Returns the current priority of the value for the specified option.
     *
     * <p>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
     * {@link IllegalArgumentException} will be thrown.
     */
    @NonNull OptionPriority getOptionPriority(@NonNull Option<?> opt);

    /**
     * Search the configuration for {@link Option}s whose id match the supplied search string.
     *
     * @param idSearchString The id string to search for. This could be a fully qualified id such as
     *                       \"<code>camerax.core.example.option</code>\" or the stem for an
     *                       option such as \"<code>
     *                       camerax.core.example</code>\".
     * @param matcher        A callback used to receive results of the search. Results will be
     *                       sent to {@link OptionMatcher#onOptionMatched(Option)} in the order
     *                       in which they are found inside this configuration. Subsequent
     *                       results will continue to be sent as long as {@link
     *                       OptionMatcher#onOptionMatched(Option)} returns {@code true}.
     */
    void findOptions(@NonNull String idSearchString, @NonNull OptionMatcher matcher);

    /**
     * Lists all options contained within this configuration.
     *
     * @return A {@link Set} of {@link Option}s contained within this configuration.
     */
    @NonNull Set<Option<?>> listOptions();

    /**
     *
     * Returns a {@link Set} of all priorities set for the specified option.
     *
     */
    @NonNull Set<OptionPriority> getPriorities(@NonNull Option<?> option);

    /**
     * A callback for retrieving results of a {@link Config.Option} search.
     */
    interface OptionMatcher {
        /**
         * Receives results from {@link Config#findOptions(String, OptionMatcher)}.
         *
         * <p>When searching for a specific option in a {@link Config}, {@link Option}s will
         * be sent to {@link #onOptionMatched(Option)} in the order in which they are found.
         *
         * @param option The matched option.
         * @return <code>false</code> if no further results are needed; <code>true</code> otherwise.
         */
        boolean onOptionMatched(@NonNull Option<?> option);
    }

    /**
     * An {@link Option} is used to set and retrieve values for settings defined in a {@link
     * Config}.
     *
     * <p>{@link Option}s can be thought of as the key in a key/value pair that makes up a setting.
     * As the name suggests, {@link Option}s are optional, and may or may not exist inside a {@link
     * Config}.
     *
     * @param <T> The type of the value for this option.
     */
    @AutoValue
    abstract class Option<T> {

        /** Prevent subclassing */
        Option() {
        }

        /**
         * Creates an {@link Option} from an id and value class.
         *
         * @param id         A unique string identifier for this option. This generally follows
         *                   the scheme
         *                   <code>&lt;owner&gt;.[optional.subCategories.]&lt;optionId&gt;</code>.
         * @param valueClass The class of the value stored by this option.
         * @param <T>        The type of the value stored by this option.
         * @return An {@link Option} object which can be used to store/retrieve values from a {@link
         * Config}.
         */
        public static <T> @NonNull Option<T> create(@NonNull String id,
                @NonNull Class<?> valueClass) {
            return Option.create(id, valueClass, /*token=*/ null);
        }

        /**
         * Creates an {@link Option} from an id, value class and token.
         *
         * @param id         A unique string identifier for this option. This generally follows
         *                   the scheme
         *                   <code>&lt;owner&gt;.[optional.subCategories.]&lt;optionId&gt;</code>.
         * @param valueClass The class of the value stored by this option.
         * @param <T>        The type of the value stored by this option.
         * @param token      An optional, type-erased object for storing more context for this
         *                   specific option. Generally this object should have static scope and be
         *                   immutable.
         * @return An {@link Option} object which can be used to store/retrieve values from a {@link
         * Config}.
         */
        @SuppressWarnings("unchecked")
        public static <T> @NonNull Option<T> create(@NonNull String id,
                @NonNull Class<?> valueClass, @Nullable Object token) {
            return new AutoValue_Config_Option<>(id, (Class<T>) valueClass, token);
        }

        /**
         * Returns the unique string identifier for this option.
         *
         * <p>This generally follows the scheme * <code>
         * &lt;owner&gt;.[optional.subCategories.]&lt;optionId&gt;
         * </code>.
         *
         * @return The identifier.
         */
        public abstract @NonNull String getId();

        /**
         * Returns the class object associated with the value for this option.
         *
         * @return The class object for the value's type.
         */
        public abstract @NonNull Class<T> getValueClass();

        /**
         * Returns the optional type-erased context object for this option.
         *
         * <p>Generally this object should have static scope and be immutable.
         *
         * @return The type-erased context object.
         */
        public abstract @Nullable Object getToken();
    }

    /**
     * Defines the priorities for resolving conflicting options.
     *
     * <p>Priority must be declared from high priority to low priority.
     */
    enum OptionPriority {
        /**
         * It takes precedence over any other option values at the risk of causing unexpected
         * behavior.
         *
         * <p>If the same option is already set, the option with this priority will overwrite the
         * value.
         *
         * <p>This priority should only be used to explicitly specify an option, such as used by
         * {@code Camera2Interop} or {@code Camera2CameraControl} to override an option.
         */
        ALWAYS_OVERRIDE,

        /**
         * This priority is higher than {@link #REQUIRED} and {@link #OPTIONAL}, and it is designed
         * to override the options internally to work around some device specific issues.
         *
         * <p>When two option values are set with this priority, the newer value takes precedence
         * over the old one. Options with this priority can still be overridden by
         * {@link #ALWAYS_OVERRIDE} which are normally used by {@code Camera2Interop}.
         */
        HIGH_PRIORITY_REQUIRED,

        /**
         * It's a required option value in order to achieve expected CameraX behavior. It takes
         * precedence over {@link #OPTIONAL} option values.
         *
         * <p>If two values are set to the same option, the value with {@link #ALWAYS_OVERRIDE}
         * priority will overwrite this priority and can potentially cause unexpected behaviors.
         *
         * <p>If two values are set to the same option with this priority, it might indicate a
         * programming error internally and an exception will be thrown when merging the configs.
         */
        REQUIRED,

        /**
         * The lowest priority, it can be overridden by any other option value. When two option
         * values are set with this priority, the newer value takes precedence over the old one.
         */
        OPTIONAL
    }

    /**
     * Returns if values with these {@link OptionPriority} conflict or not.
     *
     * <p>Currently it is not allowed the same option to have different values with priority
     * {@link OptionPriority#REQUIRED}.
     */
    static boolean hasConflict(@NonNull OptionPriority priority1,
            @NonNull OptionPriority priority2) {
        return priority1 == OptionPriority.REQUIRED
                && priority2 == OptionPriority.REQUIRED;
    }

    /**
     * Merges two configs.
     *
     * @param extendedConfig the extended config. The options in the extendedConfig will be applied
     *                       on top of the baseConfig based on the option priorities.
     * @param baseConfig the base config.
     * @return a {@link MutableOptionsBundle} of the merged config.
     */
    static @NonNull Config mergeConfigs(@Nullable Config extendedConfig,
            @Nullable Config baseConfig) {
        if (extendedConfig == null && baseConfig == null) {
            return OptionsBundle.emptyBundle();
        }

        MutableOptionsBundle mergedConfig;

        if (baseConfig != null) {
            mergedConfig = MutableOptionsBundle.from(baseConfig);
        } else {
            mergedConfig = MutableOptionsBundle.create();
        }

        if (extendedConfig != null) {
            // If any options need special handling, this is the place to do it. For now we'll
            // just copy over all options.
            for (Config.Option<?> opt : extendedConfig.listOptions()) {
                mergeOptionValue(mergedConfig, baseConfig, extendedConfig, opt);
            }
        }

        return OptionsBundle.from(mergedConfig);
    }

    /**
     * Merges a specific option value from two configs.
     *
     * @param mergedConfig   the final output config.
     * @param baseConfig     the base config contains the option value which might be overridden by
     *                       the corresponding option value in the extend config.
     * @param extendedConfig the extended config contains the option value which might override
     *                       the corresponding option value in the base config.
     * @param opt            the option to merge.
     */
    static void mergeOptionValue(@NonNull MutableOptionsBundle mergedConfig,
            @NonNull Config baseConfig,
            @NonNull Config extendedConfig,
            @NonNull Option<?> opt) {
        @SuppressWarnings("unchecked") // Options/values are being copied directly
        Config.Option<Object> objectOpt = (Config.Option<Object>) opt;

        // ResolutionSelector needs special handling to merge the underlying settings.
        if (Objects.equals(objectOpt, ImageOutputConfig.OPTION_RESOLUTION_SELECTOR)) {
            ResolutionSelector resolutionSelectorToOverride =
                    (ResolutionSelector) extendedConfig.retrieveOption(objectOpt, null);
            ResolutionSelector baseResolutionSelector =
                    (ResolutionSelector) baseConfig.retrieveOption(objectOpt, null);
            mergedConfig.insertOption(objectOpt,
                    extendedConfig.getOptionPriority(opt),
                    ResolutionSelectorUtil.overrideResolutionSelectors(
                            baseResolutionSelector, resolutionSelectorToOverride));
        } else {
            mergedConfig.insertOption(objectOpt,
                    extendedConfig.getOptionPriority(opt),
                    extendedConfig.retrieveOption(objectOpt));
        }
    }
}