1 /*
2  * Copyright 2021 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 package androidx.camera.core
17 
18 import androidx.annotation.RestrictTo
19 import androidx.annotation.RestrictTo.Scope
20 import androidx.lifecycle.LifecycleOwner
21 
22 /**
23  * A [CameraProvider] provides basic access to a set of cameras such as querying for camera
24  * existence or information.
25  *
26  * A device might have multiple cameras. According to the applications' design, they might need to
27  * search for a suitable camera which supports their functions. A [CameraProvider] allows the
28  * applications to check whether any camera exists to fulfill the requirements or to get
29  * [CameraInfo] instances of all cameras to retrieve the camera information.
30  */
31 public interface CameraProvider {
32     /**
33      * The [CameraInfo] instances of the available cameras.
34      *
35      * While iterating through all the available [CameraInfo], if one of them meets some predefined
36      * requirements, a [CameraSelector] that uniquely identifies its camera can be retrieved using
37      * [CameraInfo.getCameraSelector], which can then be used to bind [use cases][UseCase] to that
38      * camera.
39      */
40     public val availableCameraInfos: List<CameraInfo>
41 
42     /**
43      * Returns list of [CameraInfo] instances of the available concurrent cameras.
44      *
45      * The available concurrent cameras include all combinations of cameras which could operate
46      * concurrently on the device. Each list maps to one combination of these camera's [CameraInfo].
47      *
48      * For example, to select a front camera and a back camera and bind to [LifecycleOwner] with
49      * preview [UseCase], this function could be used with `bindToLifecycle`.
50      *
51      * @sample androidx.camera.lifecycle.samples.bindConcurrentCameraSample
52      * @return List of combinations of [CameraInfo].
53      */
54     @get:RestrictTo(Scope.LIBRARY_GROUP)
55     public val availableConcurrentCameraInfos: List<List<CameraInfo>>
56 
57     /**
58      * Returns whether there is a [ConcurrentCamera] bound.
59      *
60      * @return `true` if there is a [ConcurrentCamera] bound, otherwise `false`.
61      */
62     @get:RestrictTo(Scope.LIBRARY_GROUP) public val isConcurrentCameraModeOn: Boolean
63 
64     /**
65      * Checks whether this provider supports at least one camera that meets the requirements from a
66      * [CameraSelector].
67      *
68      * If this method returns `true`, then the camera selector can be used to bind use cases and
69      * retrieve a [Camera] instance.
70      *
71      * @param cameraSelector the [CameraSelector] that filters available cameras.
72      * @return `true` if the device has at least one available camera, otherwise `false`.
73      * @throws CameraInfoUnavailableException if unable to access cameras, perhaps due to
74      *   insufficient permissions.
75      */
76     @Throws(CameraInfoUnavailableException::class)
hasCameranull77     public fun hasCamera(cameraSelector: CameraSelector): Boolean
78 
79     /**
80      * Returns the [CameraInfo] instance of the camera resulted from the specified [CameraSelector].
81      *
82      * The returned [CameraInfo] corresponds to the camera that will be bound when calling
83      * `bindToLifecycle` with the specified [CameraSelector].
84      *
85      * @param cameraSelector the [CameraSelector] to use for selecting the camera to receive
86      *   information about.
87      * @return the corresponding [CameraInfo].
88      * @throws IllegalArgumentException if the given [CameraSelector] can't result in a valid camera
89      *   to provide the [CameraInfo].
90      */
91     public fun getCameraInfo(cameraSelector: CameraSelector): CameraInfo {
92         throw UnsupportedOperationException("The camera provider is not implemented properly.")
93     }
94 
95     /** Returns the [CameraXConfig] implementation type. */
96     @get:RestrictTo(Scope.LIBRARY_GROUP) @CameraXConfig.ImplType public val configImplType: Int
97 }
98