1 /*
2  * Copyright 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.camera.core;
18 
19 import androidx.annotation.RestrictTo;
20 import androidx.camera.core.impl.CameraConfig;
21 import androidx.camera.core.impl.ExtendedCameraConfigProviderStore;
22 import androidx.camera.core.impl.Identifier;
23 
24 import org.jspecify.annotations.NonNull;
25 
26 import java.util.List;
27 
28 /**
29  * An interface for filtering cameras.
30  */
31 public interface CameraFilter {
32     /**
33      * Default identifier of camera filter.
34      *
35      */
36     @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
37     Identifier DEFAULT_ID = Identifier.create(new Object());
38 
39     /**
40      * Filters a list of {@link CameraInfo}s and returns those matching the requirements.
41      *
42      * <p>If the output list contains CameraInfos not in the input list, when used by a
43      * {@link androidx.camera.core.CameraSelector} then it will result in an
44      * IllegalArgumentException thrown when calling bindToLifecycle.
45      *
46      * <p>The CameraInfo that has lower index in the list has higher priority. When used by
47      * {@link androidx.camera.core.CameraSelector.Builder#addCameraFilter(CameraFilter)}, the
48      * available cameras will be filtered by all {@link CameraFilter}s by the order they were
49      * added. The first camera in the result will be selected if there are multiple cameras left.
50      *
51      * @param cameraInfos An unmodifiable list of {@link CameraInfo}s being filtered.
52      * @return The output list of {@link CameraInfo}s that match the requirements. Users are
53      * expected to create a new list to return with.
54      *
55      * @throws IllegalArgumentException If the device cannot return a valid lens facing value,
56      *                                  it will throw this exception.
57      */
filter(@onNull List<CameraInfo> cameraInfos)58     @NonNull List<CameraInfo> filter(@NonNull List<CameraInfo> cameraInfos);
59 
60     /**
61      * Returns the id of this camera filter.
62      *
63      * <p>A camera filter can be associated with a set of camera configuration options. This
64      * means a camera filter's {@link Identifier} can be mapped to a unique {@link CameraConfig}.
65      * An example of this is extension modes, where a camera filter can represent an extension
66      * mode, and each extension mode adds a set of camera configurations to the camera that
67      * supports it. {@link ExtendedCameraConfigProviderStore#getConfigProvider(Object)} allows
68      * retrieving the {@link CameraConfig} of an extension mode given the {@link Identifier} of
69      * its camera filter.
70      *
71      */
72     @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
getIdentifier()73     default @NonNull Identifier getIdentifier() {
74         return DEFAULT_ID;
75     }
76 }
77