1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
/*
* Copyright 2021 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.camera.extensions.impl.advanced;
import android.annotation.SuppressLint;
import android.hardware.camera2.CameraCharacteristics;
import android.hardware.camera2.CaptureRequest;
import android.hardware.camera2.CaptureResult;
import android.util.Range;
import android.util.Size;
import androidx.camera.extensions.impl.ExtensionVersionImpl;
import java.util.List;
import java.util.Map;
/**
* Advanced OEM contract for implementing Extensions. ImageCapture/Preview Extensions are both
* implemented on this interface.
*
* <p>This advanced OEM contract empowers OEM to gain access to more Camera2 capability. This
* includes: (1) Add custom surfaces with specific formats like YUV, RAW, RAW_DEPTH. (2) Access to
* the capture request callbacks as well as all the images retrieved of various image formats. (3)
* Able to triggers single or repeating request with the capabilities to specify target surfaces,
* template id and parameters.
*
* <p>OEM needs to implement it with class name HdrAdvancedExtenderImpl for HDR,
* NightAdvancedExtenderImpl for night mode, BeautyAdvancedExtenderImpl for beauty mode,
* BokehAdvancedExtenderImpl for bokeh mode and AutoAdvancedExtenderImpl for auto mode.
*
* <p>OEMs are required to return true in
* {@link ExtensionVersionImpl#isAdvancedExtenderImplemented()} in order to request CameraX to
* use advanced extender over basic extender. OEM is okay to implement advanced
* extender only Or basic extender only. However the caveat of advanced-only implementation is,
* extensions will be unavailable on the apps using interfaces prior to 1.2.
*
* @since 1.2
*/
@SuppressLint("UnknownNullness")
public interface AdvancedExtenderImpl {
/**
* Indicates whether the extension is supported on the device.
*
* @param cameraId The camera2 id string of the camera.
* @param characteristicsMap A map consisting of the camera ids and the
* {@link CameraCharacteristics}s. For every camera, the map
* contains at least the CameraCharacteristics for the camera id.
* If the camera is logical camera, it will also contain associated
* physical camera ids and their CameraCharacteristics.
* @return true if the extension is supported, otherwise false
*/
boolean isExtensionAvailable(String cameraId,
Map<String, CameraCharacteristics> characteristicsMap);
/**
* Initializes the extender to be used with the specified camera.
*
* <p>This should be called before any other method on the extender. The exception is {@link
* #isExtensionAvailable}.
*
* @param cameraId The camera2 id string of the camera.
* @param characteristicsMap A map consisting of the camera ids and the
* {@link CameraCharacteristics}s. For every camera, the map
* contains at least the CameraCharacteristics for the camera id.
* If the camera is logical camera, it will also contain associated
* physical camera ids and their CameraCharacteristics.
*/
void init(String cameraId, Map<String, CameraCharacteristics> characteristicsMap);
/**
* Returns the estimated capture latency range in milliseconds for the
* target capture resolution during the calls to
* {@link SessionProcessorImpl#startCapture}. This
* includes the time spent processing the multi-frame capture request along with any additional
* time for encoding of the processed buffer in the framework if necessary.
*
* @param cameraId the camera id
* @param captureOutputSize size of the capture output surface. If it is null or not in the
* supported output sizes, maximum capture output size is used for
* the estimation.
* @param imageFormat the image format of the capture output surface.
* @return the range of estimated minimal and maximal capture latency in milliseconds.
* Returns null if no capture latency info can be provided.
*/
Range<Long> getEstimatedCaptureLatencyRange(String cameraId,
Size captureOutputSize, int imageFormat);
/**
* Returns supported output format/size map for preview. The format could be PRIVATE or
* YUV_420_888. OEM must support PRIVATE format at least. CameraX will only use resolutions
* for preview from the list.
*
* <p>The preview surface format in the CameraCaptureSession may not be identical to the
* supported preview output format returned here. Like in the basic extender interface, the
* preview PRIVATE surface could be added to the CameraCaptureSession and OEM processes it in
* the HAL. Alternatively OEM can configure a intermediate YUV surface of the same size and
* writes the output to the preview output surface.
*/
Map<Integer, List<Size>> getSupportedPreviewOutputResolutions(String cameraId);
/**
* Returns supported output format/size map for image capture. OEM is required to support
* both JPEG and YUV_420_888 format output.
*
* <p>Like in the basic extender interface, the surface created with this supported
* format/size could be either added in CameraCaptureSession with HAL processing OR it
* configures intermediate surfaces(YUV/RAW..) and writes the output to the output surface.
*/
Map<Integer, List<Size>> getSupportedCaptureOutputResolutions(String cameraId);
/**
* Returns supported output format/size map for postview image. OEM is required to support
* both JPEG and YUV_420_888 format output.
*
* <p>The surface created with this supported format/size could configure
* intermediate surfaces(YUV/RAW..) and write the output to the output surface.</p>
*
* @since 1.4
*/
Map<Integer, List<Size>> getSupportedPostviewResolutions(Size captureSize);
/**
* Returns supported output sizes for Image Analysis (YUV_420_888 format).
*
* <p>OEM can optionally support a YUV surface for ImageAnalysis along with Preview/ImageCapture
* output surfaces. If imageAnalysis YUV surface is not supported, OEM should return null or
* empty list.
*/
List<Size> getSupportedYuvAnalysisResolutions(String cameraId);
/**
* Returns a processor for activating extension sessions. It implements all the interactions
* required for starting a extension and cleanup.
*/
SessionProcessorImpl createSessionProcessor();
/**
* Returns a list of orthogonal capture request keys.
*
* <p>Any keys included in the list will be configurable by clients of the extension and will
* affect the extension functionality.</p>
*
* <p>Please note that the keys {@link CaptureRequest#JPEG_QUALITY} and
* {@link CaptureRequest#JPEG_ORIENTATION} are always supported regardless being added in the
* list or not. To support common camera operations like zoom, tap-to-focus, flash and
* exposure compensation, we recommend supporting the following keys if possible.
* <pre>
* zoom: {@link CaptureRequest#CONTROL_ZOOM_RATIO}
* {@link CaptureRequest#SCALER_CROP_REGION}
* tap-to-focus:
* {@link CaptureRequest#CONTROL_AF_MODE}
* {@link CaptureRequest#CONTROL_AF_TRIGGER}
* {@link CaptureRequest#CONTROL_AF_REGIONS}
* {@link CaptureRequest#CONTROL_AE_REGIONS}
* {@link CaptureRequest#CONTROL_AWB_REGIONS}
* flash:
* {@link CaptureRequest#CONTROL_AE_MODE}
* {@link CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER}
* {@link CaptureRequest#FLASH_MODE}
* exposure compensation:
* {@link CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION}
* </pre>
*
* @return List of supported orthogonal capture keys, or an empty list if no capture settings
* are not supported.
* @since 1.3
*/
List<CaptureRequest.Key> getAvailableCaptureRequestKeys();
/**
* Returns a list of supported capture result keys.
*
* <p>Any keys included in this list must be available as part of the registered
* {@link SessionProcessorImpl.CaptureCallback#onCaptureCompleted} callback.</p>
*
* <p>At the very minimum, it is expected that the result key list is a superset of the
* capture request keys.</p>
*
* @return List of supported capture result keys, or
* an empty list if capture results are not supported.
* @since 1.3
*/
List<CaptureResult.Key> getAvailableCaptureResultKeys();
/**
* Advertise support for {@link SessionProcessorImpl#onCaptureProcessProgressed}.
*
* @return {@code true} in case the process progress callback is supported and is expected to
* be triggered, {@code false} otherwise.
* @since 1.4
*/
public boolean isCaptureProcessProgressAvailable();
/**
* Indicates whether the extension supports the postview for still capture feature.
* If the extension is using HAL processing, false should be returned since the
* postview feature is not currently supported for this case.
*
* @return {@code true} in case postview for still capture is supported
* {@code false} otherwise.
* @since 1.4
*/
boolean isPostviewAvailable();
}
|
