1 /*
2  * Copyright 2019 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.impl;
18 
19 import android.content.Context;
20 import android.util.Pair;
21 import android.util.Size;
22 
23 import androidx.camera.core.InitializationException;
24 
25 import org.jspecify.annotations.NonNull;
26 import org.jspecify.annotations.Nullable;
27 
28 import java.util.List;
29 import java.util.Map;
30 import java.util.Set;
31 
32 /**
33  * Camera device manager to provide the guaranteed supported stream capabilities related info for
34  * all camera devices
35  */
36 public interface CameraDeviceSurfaceManager {
37 
38     /**
39      * Interface for deferring creation of a CameraDeviceSurfaceManager.
40      */
41     interface Provider {
42         /**
43          * Creates a new, initialized instance of a CameraDeviceSurfaceManager.
44          *
45          * @param context            the android context
46          * @param cameraManager      the camera manager object used to query the camera information.
47          * @param availableCameraIds current available camera ids.
48          * @return the factory instance
49          * @throws InitializationException if it fails to create the factory
50          */
newInstance(@onNull Context context, @Nullable Object cameraManager, @NonNull Set<String> availableCameraIds)51         @NonNull CameraDeviceSurfaceManager newInstance(@NonNull Context context,
52                 @Nullable Object cameraManager, @NonNull Set<String> availableCameraIds)
53                 throws InitializationException;
54     }
55 
56     /**
57      * Transform to a SurfaceConfig object with cameraId, image format and size info
58      *
59      * @param cameraMode  the working camera mode.
60      * @param cameraId    the camera id of the camera device to transform the object
61      * @param imageFormat the image format info for the surface configuration object
62      * @param size        the size info for the surface configuration object
63      * @return new {@link SurfaceConfig} object
64      */
transformSurfaceConfig( @ameraMode.Mode int cameraMode, @NonNull String cameraId, int imageFormat, @NonNull Size size)65     @Nullable SurfaceConfig transformSurfaceConfig(
66             @CameraMode.Mode int cameraMode,
67             @NonNull String cameraId,
68             int imageFormat,
69             @NonNull Size size);
70 
71     /**
72      * Retrieves a map of suggested stream specifications for the given list of use cases.
73      *
74      * @param cameraMode                        the working camera mode.
75      * @param cameraId                          the camera id of the camera device used by the
76      *                                          use cases
77      * @param existingSurfaces                  list of surfaces already configured and used by
78      *                                          the camera. The stream specifications for these
79      *                                          surface can not change.
80      * @param newUseCaseConfigsSupportedSizeMap map of configurations of the use cases to the
81      *                                          supported output sizes list that will be given a
82      *                                          suggested stream specification
83      * @param isPreviewStabilizationOn          whether the preview stabilization is enabled.
84      * @param hasVideoCapture                   whether the use cases has video capture.
85      * @return map of suggested stream specifications for given use cases
86      * @throws IllegalStateException    if not initialized
87      * @throws IllegalArgumentException if {@code newUseCaseConfigs} is an empty list, if
88      *                                  there isn't a supported combination of surfaces
89      *                                  available, or if the {@code cameraId}
90      *                                  is not a valid id.
91      */
92     @NonNull Pair<Map<UseCaseConfig<?>, StreamSpec>, Map<AttachedSurfaceInfo, StreamSpec>>
getSuggestedStreamSpecs( @ameraMode.Mode int cameraMode, @NonNull String cameraId, @NonNull List<AttachedSurfaceInfo> existingSurfaces, @NonNull Map<UseCaseConfig<?>, List<Size>> newUseCaseConfigsSupportedSizeMap, boolean isPreviewStabilizationOn, boolean hasVideoCapture)93             getSuggestedStreamSpecs(
94             @CameraMode.Mode int cameraMode,
95             @NonNull String cameraId,
96             @NonNull List<AttachedSurfaceInfo> existingSurfaces,
97             @NonNull Map<UseCaseConfig<?>, List<Size>> newUseCaseConfigsSupportedSizeMap,
98             boolean isPreviewStabilizationOn,
99             boolean hasVideoCapture);
100 }
101