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 
17 package androidx.camera.extensions.impl.advanced;
18 
19 import android.annotation.SuppressLint;
20 import android.hardware.camera2.CameraCharacteristics;
21 import android.util.Range;
22 import android.util.Size;
23 
24 import androidx.camera.extensions.impl.ExtensionVersionImpl;
25 
26 import java.util.List;
27 import java.util.Map;
28 
29 /**
30  * Advanced OEM contract for implementing Extensions. ImageCapture/Preview Extensions are both
31  * implemented on this interface.
32  *
33  * <p>This advanced OEM contract empowers OEM to gain access to more Camera2 capability. This
34  * includes: (1) Add custom surfaces with specific formats like YUV, RAW, RAW_DEPTH. (2) Access to
35  * the capture request callbacks as well as all the images retrieved of various image formats. (3)
36  * Able to triggers single or repeating request with the capabilities to specify target surfaces,
37  * template id and parameters.
38  *
39  * <p>OEM needs to implement it with class name HdrAdvancedExtenderImpl for HDR,
40  * NightAdvancedExtenderImpl for night mode, BeautyAdvancedExtenderImpl for beauty mode,
41  * BokehAdvancedExtenderImpl for bokeh mode and AutoAdvancedExtenderImpl for auto mode.
42  *
43  * <p>OEMs are required to return true in
44  * {@link ExtensionVersionImpl#isAdvancedExtenderImplemented()} in order to request CameraX to
45  * use advanced extender over basic extender. OEM is okay to implement advanced
46  * extender only Or basic extender only. However the caveat of advanced-only implementation is,
47  * extensions will be unavailable on the apps using interfaces prior to 1.2.
48  *
49  * @since 1.2
50  */
51 @SuppressLint("UnknownNullness")
52 public interface AdvancedExtenderImpl {
53 
54     /**
55      * Indicates whether the extension is supported on the device.
56      *
57      * @param cameraId           The camera2 id string of the camera.
58      * @param characteristicsMap A map consisting of the camera ids and the
59      *                           {@link CameraCharacteristics}s. For every camera, the map
60      *                           contains at least the CameraCharacteristics for the camera id.
61      *                           If the camera is logical camera, it will also contain associated
62      *                           physical camera ids and their CameraCharacteristics.
63      * @return true if the extension is supported, otherwise false
64      */
isExtensionAvailable(String cameraId, Map<String, CameraCharacteristics> characteristicsMap)65     boolean isExtensionAvailable(String cameraId,
66             Map<String, CameraCharacteristics> characteristicsMap);
67 
68     /**
69      * Initializes the extender to be used with the specified camera.
70      *
71      * <p>This should be called before any other method on the extender. The exception is {@link
72      * #isExtensionAvailable}.
73      *
74      * @param cameraId           The camera2 id string of the camera.
75      * @param characteristicsMap A map consisting of the camera ids and the
76      *                           {@link CameraCharacteristics}s. For every camera, the map
77      *                           contains at least the CameraCharacteristics for the camera id.
78      *                           If the camera is logical camera, it will also contain associated
79      *                           physical camera ids and their CameraCharacteristics.
80      */
init(String cameraId, Map<String, CameraCharacteristics> characteristicsMap)81     void init(String cameraId, Map<String, CameraCharacteristics> characteristicsMap);
82 
83     /**
84      * Returns the estimated capture latency range in milliseconds for the
85      * target capture resolution during the calls to
86      * {@link SessionProcessorImpl#startCapture}. This
87      * includes the time spent processing the multi-frame capture request along with any additional
88      * time for encoding of the processed buffer in the framework if necessary.
89      *
90      * @param cameraId          the camera id
91      * @param captureOutputSize size of the capture output surface. If it is null or not in the
92      *                          supported output sizes, maximum capture output size is used for
93      *                          the estimation.
94      * @param imageFormat the image format of the capture output surface.
95      * @return the range of estimated minimal and maximal capture latency in milliseconds.
96      * Returns null if no capture latency info can be provided.
97      */
getEstimatedCaptureLatencyRange(String cameraId, Size captureOutputSize, int imageFormat)98     Range<Long> getEstimatedCaptureLatencyRange(String cameraId,
99             Size captureOutputSize, int imageFormat);
100 
101     /**
102      * Returns supported output format/size map for preview. The format could be PRIVATE or
103      * YUV_420_888. OEM must support PRIVATE format at least. CameraX will only use resolutions
104      * for preview from the list.
105      *
106      * <p>The preview surface format in the CameraCaptureSession may not be identical to the
107      * supported preview output format returned here. Like in the basic extender interface, the
108      * preview PRIVATE surface could be added to the CameraCaptureSession and OEM processes it in
109      * the HAL. Alternatively OEM can configure a intermediate YUV surface of the same size and
110      * writes the output to the preview output surface.
111      */
getSupportedPreviewOutputResolutions(String cameraId)112     Map<Integer, List<Size>> getSupportedPreviewOutputResolutions(String cameraId);
113 
114     /**
115      * Returns supported output format/size map for image capture. OEM is required to support
116      * both JPEG and YUV_420_888 format output.
117      *
118      * <p>Like in the basic extender interface, the surface created with this supported
119      * format/size could be either added in CameraCaptureSession with HAL processing OR it
120      * configures intermediate surfaces(YUV/RAW..) and writes the output to the output surface.
121      */
getSupportedCaptureOutputResolutions(String cameraId)122     Map<Integer, List<Size>> getSupportedCaptureOutputResolutions(String cameraId);
123 
124     /**
125      * Returns supported output sizes for Image Analysis (YUV_420_888 format).
126      *
127      * <p>OEM can optionally support a YUV surface for ImageAnalysis along with Preview/ImageCapture
128      * output surfaces. If imageAnalysis YUV surface is not supported, OEM will return null or
129      * empty list.
130      */
getSupportedYuvAnalysisResolutions(String cameraId)131     List<Size> getSupportedYuvAnalysisResolutions(String cameraId);
132 
133     /**
134      * Returns a processor for activating extension sessions. It implements all the interactions
135      * required for starting a extension and cleanup.
136      */
createSessionProcessor()137     SessionProcessorImpl createSessionProcessor();
138 }
139