1 /*
2  * Copyright 2023 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.concurrent;
18 
19 
20 import android.hardware.camera2.CameraManager;
21 
22 import androidx.annotation.IntDef;
23 import androidx.annotation.RestrictTo;
24 import androidx.camera.core.CameraInfo;
25 import androidx.camera.core.CameraSelector;
26 import androidx.camera.core.impl.CameraStateRegistry;
27 
28 import org.jspecify.annotations.NonNull;
29 import org.jspecify.annotations.Nullable;
30 
31 import java.lang.annotation.Retention;
32 import java.lang.annotation.RetentionPolicy;
33 import java.util.List;
34 
35 /**
36  * Coordinator for concurrent camera.
37  *
38  * <p>It coordinates the order of camera device open and camera capture session configuration.
39  * All camera devices intended to be operated concurrently, must be opened before configuring
40  * sessions on any of the camera devices.
41  *
42  */
43 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
44 public interface CameraCoordinator {
45 
46     int CAMERA_OPERATING_MODE_UNSPECIFIED = 0;
47 
48     int CAMERA_OPERATING_MODE_SINGLE = 1;
49 
50     int CAMERA_OPERATING_MODE_CONCURRENT = 2;
51 
52     @RestrictTo(RestrictTo.Scope.LIBRARY)
53     @IntDef({CAMERA_OPERATING_MODE_UNSPECIFIED,
54             CAMERA_OPERATING_MODE_SINGLE,
55             CAMERA_OPERATING_MODE_CONCURRENT})
56     @Retention(RetentionPolicy.SOURCE)
57     public @interface CameraOperatingMode {
58     }
59 
60     /**
61      * Returns concurrent camera selectors, which are converted from concurrent camera ids
62      * queried from {@link CameraManager#getConcurrentCameraIds()}.
63      *
64      * <p>This API is exposed to external users to select one combination of supported concurrent
65      * {@link CameraSelector}s to bind.
66      *
67      * @return List of list of {@link CameraSelector}.
68      */
getConcurrentCameraSelectors()69     @NonNull List<List<CameraSelector>> getConcurrentCameraSelectors();
70 
71     /**
72      * Gets active concurrent camera infos.
73      *
74      * @return list of active concurrent camera infos.
75      */
getActiveConcurrentCameraInfos()76     @NonNull List<CameraInfo> getActiveConcurrentCameraInfos();
77 
78     /**
79      * Sets active concurrent camera infos.
80      *
81      * @param cameraInfos list of active concurrent camera infos.
82      */
setActiveConcurrentCameraInfos(@onNull List<CameraInfo> cameraInfos)83     void setActiveConcurrentCameraInfos(@NonNull List<CameraInfo> cameraInfos);
84 
85     /**
86      * Returns paired camera id in concurrent mode.
87      *
88      * <p>The paired camera id dictionary is constructed when constructor is called. This
89      * internal API is used to look up paired camera id when coordinating device open and session
90      * config in {@link CameraStateRegistry}. Currently only dual cameras will be supported in
91      * concurrent mode.
92      *
93      * @param cameraId camera id.
94      * @return The paired camera id if exists or null if paired camera not exists.
95      */
getPairedConcurrentCameraId(@onNull String cameraId)96     @Nullable String getPairedConcurrentCameraId(@NonNull String cameraId);
97 
98     /**
99      * Returns camera operating mode.
100      *
101      * @return camera operating mode including unspecific, single or concurrent.
102      */
103     @CameraOperatingMode
getCameraOperatingMode()104     int getCameraOperatingMode();
105 
106     /**
107      * Sets concurrent camera mode.
108      *
109      * <p>This internal API will be called when user binds user cases to cameras, which will
110      * enable or disable concurrent camera mode based on the input config.
111      *
112      * @param cameraOperatingMode camera operating mode including unspecific, single or concurrent.
113      */
setCameraOperatingMode(@ameraOperatingMode int cameraOperatingMode)114     void setCameraOperatingMode(@CameraOperatingMode int cameraOperatingMode);
115 
116     /**
117      * Adds listener for concurrent camera mode update.
118      * @param listener {@link ConcurrentCameraModeListener}.
119      */
addListener(@onNull ConcurrentCameraModeListener listener)120     void addListener(@NonNull ConcurrentCameraModeListener listener);
121 
122     /**
123      * Removes listener for concurrent camera mode update.
124      * @param listener {@link ConcurrentCameraModeListener}.
125      */
removeListener(@onNull ConcurrentCameraModeListener listener)126     void removeListener(@NonNull ConcurrentCameraModeListener listener);
127 
128     /**
129      * Clean up all the resources when CameraX shutdown.
130      */
shutdown()131     void shutdown();
132 
133     /**
134      * Interface for concurrent camera mode update.
135      *
136      * <p>Everytime user changes {@link CameraOperatingMode}, the observer will be notified and
137      * update related states or parameters accordingly. E.g. in {@link CameraStateRegistry}, we
138      * will update the number of max allowed cameras.
139      */
140     interface ConcurrentCameraModeListener {
onCameraOperatingModeUpdated( @ameraOperatingMode int prevMode, @CameraOperatingMode int currMode)141         void onCameraOperatingModeUpdated(
142                 @CameraOperatingMode int prevMode,
143                 @CameraOperatingMode int currMode);
144     }
145 }
146