1 /* 2 * Copyright (C) 2013 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 android.hardware.camera2; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.annotation.IntDef; 22 import android.annotation.SystemApi; 23 import android.annotation.TestApi; 24 import static android.hardware.camera2.ICameraDeviceUser.NORMAL_MODE; 25 import static android.hardware.camera2.ICameraDeviceUser.CONSTRAINED_HIGH_SPEED_MODE; 26 import android.hardware.camera2.params.InputConfiguration; 27 import android.hardware.camera2.params.StreamConfigurationMap; 28 import android.hardware.camera2.params.OutputConfiguration; 29 import android.hardware.camera2.params.SessionConfiguration; 30 import android.os.Handler; 31 import android.view.Surface; 32 33 import java.util.List; 34 import java.util.Set; 35 import java.lang.annotation.Retention; 36 import java.lang.annotation.RetentionPolicy; 37 38 /** 39 * <p>The CameraDevice class is a representation of a single camera connected to an 40 * Android device, allowing for fine-grain control of image capture and 41 * post-processing at high frame rates.</p> 42 * 43 * <p>Your application must declare the 44 * {@link android.Manifest.permission#CAMERA Camera} permission in its manifest 45 * in order to access camera devices.</p> 46 * 47 * <p>A given camera device may provide support at one of several levels defined 48 * in {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}. 49 * If a device supports {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} level, 50 * the camera device is running in backward compatibility mode and has minimum camera2 API support. 51 * If a device supports the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} 52 * level, then Camera2 exposes a feature set that is roughly equivalent to the older 53 * {@link android.hardware.Camera Camera} API, although with a cleaner and more 54 * efficient interface. 55 * If a device supports the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL EXTERNAL} 56 * level, then the device is a removable camera that provides similar but slightly less features 57 * as the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} level. 58 * Devices that implement the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} or 59 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL3} level of support 60 * provide substantially improved capabilities over the older camera 61 * API. If your application requires a full-level device for 62 * proper operation, declare the "android.hardware.camera.level.full" feature in your 63 * manifest.</p> 64 * 65 * @see CameraManager#openCamera 66 * @see android.Manifest.permission#CAMERA 67 * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL 68 */ 69 public abstract class CameraDevice implements AutoCloseable { 70 71 /** 72 * Create a request suitable for a camera preview window. Specifically, this 73 * means that high frame rate is given priority over the highest-quality 74 * post-processing. These requests would normally be used with the 75 * {@link CameraCaptureSession#setRepeatingRequest} method. 76 * This template is guaranteed to be supported on all camera devices. 77 * 78 * @see #createCaptureRequest 79 */ 80 public static final int TEMPLATE_PREVIEW = 1; 81 82 /** 83 * Create a request suitable for still image capture. Specifically, this 84 * means prioritizing image quality over frame rate. These requests would 85 * commonly be used with the {@link CameraCaptureSession#capture} method. 86 * This template is guaranteed to be supported on all camera devices except 87 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_DEPTH_OUTPUT DEPTH_OUTPUT} devices 88 * that are not {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE 89 * BACKWARD_COMPATIBLE}. 90 * @see #createCaptureRequest 91 */ 92 public static final int TEMPLATE_STILL_CAPTURE = 2; 93 94 /** 95 * Create a request suitable for video recording. Specifically, this means 96 * that a stable frame rate is used, and post-processing is set for 97 * recording quality. These requests would commonly be used with the 98 * {@link CameraCaptureSession#setRepeatingRequest} method. 99 * This template is guaranteed to be supported on all camera devices except 100 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_DEPTH_OUTPUT DEPTH_OUTPUT} devices 101 * that are not {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE 102 * BACKWARD_COMPATIBLE}. 103 * 104 * @see #createCaptureRequest 105 */ 106 public static final int TEMPLATE_RECORD = 3; 107 108 /** 109 * Create a request suitable for still image capture while recording 110 * video. Specifically, this means maximizing image quality without 111 * disrupting the ongoing recording. These requests would commonly be used 112 * with the {@link CameraCaptureSession#capture} method while a request based on 113 * {@link #TEMPLATE_RECORD} is is in use with {@link CameraCaptureSession#setRepeatingRequest}. 114 * This template is guaranteed to be supported on all camera devices except 115 * legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 116 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) and 117 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_DEPTH_OUTPUT DEPTH_OUTPUT} devices 118 * that are not {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE 119 * BACKWARD_COMPATIBLE}. 120 * 121 * @see #createCaptureRequest 122 */ 123 public static final int TEMPLATE_VIDEO_SNAPSHOT = 4; 124 125 /** 126 * Create a request suitable for zero shutter lag still capture. This means 127 * means maximizing image quality without compromising preview frame rate. 128 * AE/AWB/AF should be on auto mode. This is intended for application-operated ZSL. For 129 * device-operated ZSL, use {@link CaptureRequest#CONTROL_ENABLE_ZSL} if available. 130 * This template is guaranteed to be supported on camera devices that support the 131 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_PRIVATE_REPROCESSING PRIVATE_REPROCESSING} 132 * capability or the 133 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_YUV_REPROCESSING YUV_REPROCESSING} 134 * capability. 135 * 136 * @see #createCaptureRequest 137 * @see CaptureRequest#CONTROL_ENABLE_ZSL 138 */ 139 public static final int TEMPLATE_ZERO_SHUTTER_LAG = 5; 140 141 /** 142 * A basic template for direct application control of capture 143 * parameters. All automatic control is disabled (auto-exposure, auto-white 144 * balance, auto-focus), and post-processing parameters are set to preview 145 * quality. The manual capture parameters (exposure, sensitivity, and so on) 146 * are set to reasonable defaults, but should be overriden by the 147 * application depending on the intended use case. 148 * This template is guaranteed to be supported on camera devices that support the 149 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR MANUAL_SENSOR} 150 * capability. 151 * 152 * @see #createCaptureRequest 153 */ 154 public static final int TEMPLATE_MANUAL = 6; 155 156 /** @hide */ 157 @Retention(RetentionPolicy.SOURCE) 158 @IntDef(prefix = {"TEMPLATE_"}, value = 159 {TEMPLATE_PREVIEW, 160 TEMPLATE_STILL_CAPTURE, 161 TEMPLATE_RECORD, 162 TEMPLATE_VIDEO_SNAPSHOT, 163 TEMPLATE_ZERO_SHUTTER_LAG, 164 TEMPLATE_MANUAL}) 165 public @interface RequestTemplate {}; 166 167 /** 168 * Get the ID of this camera device. 169 * 170 * <p>This matches the ID given to {@link CameraManager#openCamera} to instantiate this 171 * this camera device.</p> 172 * 173 * <p>This ID can be used to query the camera device's {@link 174 * CameraCharacteristics fixed properties} with {@link 175 * CameraManager#getCameraCharacteristics}.</p> 176 * 177 * <p>This method can be called even if the device has been closed or has encountered 178 * a serious error.</p> 179 * 180 * @return the ID for this camera device 181 * 182 * @see CameraManager#getCameraCharacteristics 183 * @see CameraManager#getCameraIdList 184 */ 185 @NonNull getId()186 public abstract String getId(); 187 188 /** 189 * <p>Create a new camera capture session by providing the target output set of Surfaces to the 190 * camera device.</p> 191 * 192 * <p>The active capture session determines the set of potential output Surfaces for 193 * the camera device for each capture request. A given request may use all 194 * or only some of the outputs. Once the CameraCaptureSession is created, requests can be 195 * submitted with {@link CameraCaptureSession#capture capture}, 196 * {@link CameraCaptureSession#captureBurst captureBurst}, 197 * {@link CameraCaptureSession#setRepeatingRequest setRepeatingRequest}, or 198 * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}.</p> 199 * 200 * <p>Surfaces suitable for inclusion as a camera output can be created for 201 * various use cases and targets:</p> 202 * 203 * <ul> 204 * 205 * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Once the SurfaceView's 206 * Surface is {@link android.view.SurfaceHolder.Callback#surfaceCreated created}, set the size 207 * of the Surface with {@link android.view.SurfaceHolder#setFixedSize} to be one of the sizes 208 * returned by {@link StreamConfigurationMap#getOutputSizes(Class) 209 * getOutputSizes(SurfaceHolder.class)} and then obtain the Surface by calling {@link 210 * android.view.SurfaceHolder#getSurface}. If the size is not set by the application, it will 211 * be rounded to the nearest supported size less than 1080p, by the camera device.</li> 212 * 213 * <li>For accessing through an OpenGL texture via a {@link android.graphics.SurfaceTexture 214 * SurfaceTexture}: Set the size of the SurfaceTexture with {@link 215 * android.graphics.SurfaceTexture#setDefaultBufferSize} to be one of the sizes returned by 216 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(SurfaceTexture.class)} 217 * before creating a Surface from the SurfaceTexture with {@link Surface#Surface}. If the size 218 * is not set by the application, it will be set to be the smallest supported size less than 219 * 1080p, by the camera device.</li> 220 * 221 * <li>For recording with {@link android.media.MediaCodec}: Call 222 * {@link android.media.MediaCodec#createInputSurface} after configuring 223 * the media codec to use one of the sizes returned by 224 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaCodec.class)} 225 * </li> 226 * 227 * <li>For recording with {@link android.media.MediaRecorder}: Call 228 * {@link android.media.MediaRecorder#getSurface} after configuring the media recorder to use 229 * one of the sizes returned by 230 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaRecorder.class)}, 231 * or configuring it to use one of the supported 232 * {@link android.media.CamcorderProfile CamcorderProfiles}.</li> 233 * 234 * <li>For efficient YUV processing with {@link android.renderscript}: 235 * Create a RenderScript 236 * {@link android.renderscript.Allocation Allocation} with a supported YUV 237 * type, the IO_INPUT flag, and one of the sizes returned by 238 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(Allocation.class)}, 239 * Then obtain the Surface with 240 * {@link android.renderscript.Allocation#getSurface}.</li> 241 * 242 * <li>For access to RAW, uncompressed YUV, or compressed JPEG data in the application: Create an 243 * {@link android.media.ImageReader} object with one of the supported output formats given by 244 * {@link StreamConfigurationMap#getOutputFormats()}, setting its size to one of the 245 * corresponding supported sizes by passing the chosen output format into 246 * {@link StreamConfigurationMap#getOutputSizes(int)}. Then obtain a 247 * {@link android.view.Surface} from it with {@link android.media.ImageReader#getSurface()}. 248 * If the ImageReader size is not set to a supported size, it will be rounded to a supported 249 * size less than 1080p by the camera device. 250 * </li> 251 * 252 * </ul> 253 * 254 * <p>The camera device will query each Surface's size and formats upon this 255 * call, so they must be set to a valid setting at this time.</p> 256 * 257 * <p>It can take several hundred milliseconds for the session's configuration to complete, 258 * since camera hardware may need to be powered on or reconfigured. Once the configuration is 259 * complete and the session is ready to actually capture data, the provided 260 * {@link CameraCaptureSession.StateCallback}'s 261 * {@link CameraCaptureSession.StateCallback#onConfigured} callback will be called.</p> 262 * 263 * <p>If a prior CameraCaptureSession already exists when this method is called, the previous 264 * session will no longer be able to accept new capture requests and will be closed. Any 265 * in-progress capture requests made on the prior session will be completed before it's closed. 266 * {@link CameraCaptureSession.StateCallback#onConfigured} for the new session may be invoked 267 * before {@link CameraCaptureSession.StateCallback#onClosed} is invoked for the prior 268 * session. Once the new session is {@link CameraCaptureSession.StateCallback#onConfigured 269 * configured}, it is able to start capturing its own requests. To minimize the transition time, 270 * the {@link CameraCaptureSession#abortCaptures} call can be used to discard the remaining 271 * requests for the prior capture session before a new one is created. Note that once the new 272 * session is created, the old one can no longer have its captures aborted.</p> 273 * 274 * <p>Using larger resolution outputs, or more outputs, can result in slower 275 * output rate from the device.</p> 276 * 277 * <p>Configuring a session with an empty or null list will close the current session, if 278 * any. This can be used to release the current session's target surfaces for another use.</p> 279 * 280 * <p>While any of the sizes from {@link StreamConfigurationMap#getOutputSizes} can be used when 281 * a single output stream is configured, a given camera device may not be able to support all 282 * combination of sizes, formats, and targets when multiple outputs are configured at once. The 283 * tables below list the maximum guaranteed resolutions for combinations of streams and targets, 284 * given the capabilities of the camera device.</p> 285 * 286 * <p>If an application tries to create a session using a set of targets that exceed the limits 287 * described in the below tables, one of three possibilities may occur. First, the session may 288 * be successfully created and work normally. Second, the session may be successfully created, 289 * but the camera device won't meet the frame rate guarantees as described in 290 * {@link StreamConfigurationMap#getOutputMinFrameDuration}. Or third, if the output set 291 * cannot be used at all, session creation will fail entirely, with 292 * {@link CameraCaptureSession.StateCallback#onConfigureFailed} being invoked.</p> 293 * 294 * <p>For the type column, {@code PRIV} refers to any target whose available sizes are found 295 * using {@link StreamConfigurationMap#getOutputSizes(Class)} with no direct application-visible 296 * format, {@code YUV} refers to a target Surface using the 297 * {@link android.graphics.ImageFormat#YUV_420_888} format, {@code JPEG} refers to the 298 * {@link android.graphics.ImageFormat#JPEG} format, and {@code RAW} refers to the 299 * {@link android.graphics.ImageFormat#RAW_SENSOR} format.</p> 300 * 301 * <p>For the maximum size column, {@code PREVIEW} refers to the best size match to the 302 * device's screen resolution, or to 1080p ({@code 1920x1080}), whichever is 303 * smaller. {@code RECORD} refers to the camera device's maximum supported recording resolution, 304 * as determined by {@link android.media.CamcorderProfile}. And {@code MAXIMUM} refers to the 305 * camera device's maximum output resolution for that format or target from 306 * {@link StreamConfigurationMap#getOutputSizes}.</p> 307 * 308 * <p>To use these tables, determine the number and the formats/targets of outputs needed, and 309 * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes 310 * that can be used; it is guaranteed that for those targets, the listed sizes and anything 311 * smaller from the list given by {@link StreamConfigurationMap#getOutputSizes} can be 312 * successfully used to create a session. For example, if a row indicates that a 8 megapixel 313 * (MP) YUV_420_888 output can be used together with a 2 MP {@code PRIV} output, then a session 314 * can be created with targets {@code [8 MP YUV, 2 MP PRIV]} or targets {@code [2 MP YUV, 2 MP 315 * PRIV]}; but a session with targets {@code [8 MP YUV, 4 MP PRIV]}, targets {@code [4 MP YUV, 4 316 * MP PRIV]}, or targets {@code [8 MP PRIV, 2 MP YUV]} would not be guaranteed to work, unless 317 * some other row of the table lists such a combination.</p> 318 * 319 * <style scoped> 320 * #rb { border-right-width: thick; } 321 * </style> 322 * <p>Legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 323 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at 324 * least the following stream combinations: 325 * 326 * <table> 327 * <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr> 328 * <tr> <th colspan="2" id="rb">Target 1</th> <th colspan="2" id="rb">Target 2</th> <th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 329 * <tr> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th></tr> 330 * <tr> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>Simple preview, GPU video processing, or no-preview video recording.</td> </tr> 331 * <tr> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-viewfinder still image capture.</td> </tr> 332 * <tr> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>In-application video/image processing.</td> </tr> 333 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Standard still imaging.</td> </tr> 334 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>In-app processing plus still capture.</td> </tr> 335 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td colspan="2" id="rb"></td> <td>Standard recording.</td> </tr> 336 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td colspan="2" id="rb"></td> <td>Preview plus in-app processing.</td> </tr> 337 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Still capture plus in-app processing.</td> </tr> 338 * </table><br> 339 * </p> 340 * 341 * <p>Limited-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 342 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices 343 * support at least the following stream combinations in addition to those for 344 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: 345 * 346 * <table> 347 * <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr> 348 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 349 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 350 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>High-resolution video recording with preview.</td> </tr> 351 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>High-resolution in-app video processing with preview.</td> </tr> 352 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>Two-input in-app video processing.</td> </tr> 353 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code RECORD }</td> <td>{@code JPEG}</td><td id="rb">{@code RECORD }</td> <td>High-resolution recording with video snapshot.</td> </tr> 354 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td>{@code JPEG}</td><td id="rb">{@code RECORD }</td> <td>High-resolution in-app processing with video snapshot.</td> </tr> 355 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Two-input in-app processing with still capture.</td> </tr> 356 * </table><br> 357 * </p> 358 * 359 * <p>FULL-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 360 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices 361 * support at least the following stream combinations in addition to those for 362 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 363 * 364 * <table> 365 * <tr><th colspan="7">FULL-level additional guaranteed configurations</th></tr> 366 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 367 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 368 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution GPU processing with preview.</td> </tr> 369 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution in-app processing with preview.</td> </tr> 370 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution two-input in-app processsing.</td> </tr> 371 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Video recording with maximum-size video snapshot</td> </tr> 372 * <tr> <td>{@code YUV }</td><td id="rb">{@code 640x480}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Standard video recording plus maximum-resolution in-app processing.</td> </tr> 373 * <tr> <td>{@code YUV }</td><td id="rb">{@code 640x480}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Preview plus two-input maximum-resolution in-app processing.</td> </tr> 374 * </table><br> 375 * </p> 376 * 377 * <p>RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 378 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support 379 * at least the following stream combinations on both 380 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and 381 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 382 * 383 * <table> 384 * <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr> 385 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 386 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 387 * <tr> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-preview DNG capture.</td> </tr> 388 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Standard DNG capture.</td> </tr> 389 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>In-app processing plus DNG capture.</td> </tr> 390 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Video recording with DNG capture.</td> </tr> 391 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Preview with in-app processing and DNG capture.</td> </tr> 392 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Two-input in-app processing plus DNG capture.</td> </tr> 393 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Still capture with simultaneous JPEG and DNG.</td> </tr> 394 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>In-app processing with simultaneous JPEG and DNG.</td> </tr> 395 * </table><br> 396 * </p> 397 * 398 * <p>BURST-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 399 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices 400 * support at least the below stream combinations in addition to those for 401 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices. Note that all 402 * FULL-level devices support the BURST capability, and the below list is a strict subset of the 403 * list for FULL-level devices, so this table is only relevant for LIMITED-level devices that 404 * support the BURST_CAPTURE capability. 405 * 406 * <table> 407 * <tr><th colspan="5">BURST-capability additional guaranteed configurations</th></tr> 408 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th rowspan="2">Sample use case(s)</th> </tr> 409 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 410 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td>Maximum-resolution GPU processing with preview.</td> </tr> 411 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Maximum-resolution in-app processing with preview.</td> </tr> 412 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Maximum-resolution two-input in-app processsing.</td> </tr> 413 * </table><br> 414 * </p> 415 * 416 * <p>LEVEL-3 ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 417 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL_3}) 418 * support at least the following stream combinations in addition to the combinations for 419 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and for 420 * RAW capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 421 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}): 422 * 423 * <table> 424 * <tr><th colspan="11">LEVEL-3 additional guaranteed configurations</th></tr> 425 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th><th colspan="2" id="rb">Target 4</th><th rowspan="2">Sample use case(s)</th> </tr> 426 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 427 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code 640x480}</td> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>In-app viewfinder analysis with dynamic selection of output format.</td> </tr> 428 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code 640x480}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>In-app viewfinder analysis with dynamic selection of output format.</td> </tr> 429 * </table><br> 430 * </p> 431 * 432 * <p>MONOCHROME-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} 433 * includes {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME MONOCHROME}) devices 434 * supporting {@link android.graphics.ImageFormat#Y8 Y8} support substituting {@code YUV} 435 * streams with {@code Y8} in all guaranteed stream combinations for the device's hardware level 436 * and capabilities.</p> 437 * 438 * <p>Devices capable of outputting HEIC formats ({@link StreamConfigurationMap#getOutputFormats} 439 * contains {@link android.graphics.ImageFormat#HEIC}) will support substituting {@code JPEG} 440 * streams with {@code HEIC} in all guaranteed stream combinations for the device's hardware 441 * level and capabilities. Calling createCaptureSession with both JPEG and HEIC outputs is not 442 * supported.</p> 443 * 444 * <p>Clients can access the above mandatory stream combination tables via 445 * {@link android.hardware.camera2.params.MandatoryStreamCombination}.</p> 446 * 447 * <p>Since the capabilities of camera devices vary greatly, a given camera device may support 448 * target combinations with sizes outside of these guarantees, but this can only be tested for 449 * by calling {@link #isSessionConfigurationSupported} or attempting to create a session with 450 * such targets.</p> 451 * 452 * <p>Exception on 176x144 (QCIF) resolution: 453 * Camera devices usually have a fixed capability for downscaling from larger resolution to 454 * smaller, and the QCIF resolution sometimes is not fully supported due to this 455 * limitation on devices with high-resolution image sensors. Therefore, trying to configure a 456 * QCIF resolution stream together with any other stream larger than 1920x1080 resolution 457 * (either width or height) might not be supported, and capture session creation will fail if it 458 * is not.</p> 459 * 460 * @param outputs The new set of Surfaces that should be made available as 461 * targets for captured image data. 462 * @param callback The callback to notify about the status of the new capture session. 463 * @param handler The handler on which the callback should be invoked, or {@code null} to use 464 * the current thread's {@link android.os.Looper looper}. 465 * 466 * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements, 467 * the callback is null, or the handler is null but the current 468 * thread has no looper. 469 * @throws CameraAccessException if the camera device is no longer connected or has 470 * encountered a fatal error 471 * @throws IllegalStateException if the camera device has been closed 472 * 473 * @see CameraCaptureSession 474 * @see StreamConfigurationMap#getOutputFormats() 475 * @see StreamConfigurationMap#getOutputSizes(int) 476 * @see StreamConfigurationMap#getOutputSizes(Class) 477 */ createCaptureSession(@onNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)478 public abstract void createCaptureSession(@NonNull List<Surface> outputs, 479 @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler) 480 throws CameraAccessException; 481 482 /** 483 * <p>Create a new camera capture session by providing the target output set of Surfaces and 484 * its corresponding surface configuration to the camera device.</p> 485 * 486 * @see #createCaptureSession 487 * @see OutputConfiguration 488 */ createCaptureSessionByOutputConfigurations( List<OutputConfiguration> outputConfigurations, CameraCaptureSession.StateCallback callback, @Nullable Handler handler)489 public abstract void createCaptureSessionByOutputConfigurations( 490 List<OutputConfiguration> outputConfigurations, 491 CameraCaptureSession.StateCallback callback, @Nullable Handler handler) 492 throws CameraAccessException; 493 /** 494 * Create a new reprocessable camera capture session by providing the desired reprocessing 495 * input Surface configuration and the target output set of Surfaces to the camera device. 496 * 497 * <p>If a camera device supports YUV reprocessing 498 * ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_YUV_REPROCESSING}) or PRIVATE 499 * reprocessing 500 * ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_PRIVATE_REPROCESSING}), besides 501 * the capture session created via {@link #createCaptureSession createCaptureSession}, the 502 * application can also create a reprocessable capture session to submit reprocess capture 503 * requests in addition to regular capture requests. A reprocess capture request takes the next 504 * available buffer from the session's input Surface, and sends it through the camera device's 505 * processing pipeline again, to produce buffers for the request's target output Surfaces. No 506 * new image data is captured for a reprocess request. However the input buffer provided by 507 * the application must be captured previously by the same camera device in the same session 508 * directly (e.g. for Zero-Shutter-Lag use case) or indirectly (e.g. combining multiple output 509 * images).</p> 510 * 511 * <p>The active reprocessable capture session determines an input {@link Surface} and the set 512 * of potential output Surfaces for the camera devices for each capture request. The application 513 * can use {@link #createCaptureRequest createCaptureRequest} to create regular capture requests 514 * to capture new images from the camera device, and use {@link #createReprocessCaptureRequest 515 * createReprocessCaptureRequest} to create reprocess capture requests to process buffers from 516 * the input {@link Surface}. Some combinations of output Surfaces in a session may not be used 517 * in a request simultaneously. The guaranteed combinations of output Surfaces that can be used 518 * in a request simultaneously are listed in the tables under {@link #createCaptureSession 519 * createCaptureSession}. All the output Surfaces in one capture request will come from the 520 * same source, either from a new capture by the camera device, or from the input Surface 521 * depending on if the request is a reprocess capture request.</p> 522 * 523 * <p>Input formats and sizes supported by the camera device can be queried via 524 * {@link StreamConfigurationMap#getInputFormats} and 525 * {@link StreamConfigurationMap#getInputSizes}. For each supported input format, the camera 526 * device supports a set of output formats and sizes for reprocessing that can be queried via 527 * {@link StreamConfigurationMap#getValidOutputFormatsForInput} and 528 * {@link StreamConfigurationMap#getOutputSizes}. While output Surfaces with formats that 529 * aren't valid reprocess output targets for the input configuration can be part of a session, 530 * they cannot be used as targets for a reprocessing request.</p> 531 * 532 * <p>Since the application cannot access {@link android.graphics.ImageFormat#PRIVATE} images 533 * directly, an output Surface created by {@link android.media.ImageReader#newInstance} with 534 * {@link android.graphics.ImageFormat#PRIVATE} as the format will be considered as intended to 535 * be used for reprocessing input and thus the {@link android.media.ImageReader} size must 536 * match one of the supported input sizes for {@link android.graphics.ImageFormat#PRIVATE} 537 * format. Otherwise, creating a reprocessable capture session will fail.</p> 538 * 539 * <p>The guaranteed stream configurations listed in 540 * {@link #createCaptureSession createCaptureSession} are also guaranteed to work for 541 * {@link #createReprocessableCaptureSession createReprocessableCaptureSession}. In addition, 542 * the configurations in the tables below are also guaranteed for creating a reprocessable 543 * capture session if the camera device supports YUV reprocessing or PRIVATE reprocessing. 544 * However, not all output targets used to create a reprocessable session may be used in a 545 * {@link CaptureRequest} simultaneously. For devices that support only 1 output target in a 546 * reprocess {@link CaptureRequest}, submitting a reprocess {@link CaptureRequest} with multiple 547 * output targets will result in a {@link CaptureFailure}. For devices that support multiple 548 * output targets in a reprocess {@link CaptureRequest}, the guaranteed output targets that can 549 * be included in a {@link CaptureRequest} simultaneously are listed in the tables under 550 * {@link #createCaptureSession createCaptureSession}. For example, with a FULL-capability 551 * ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} {@code == } 552 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) device that supports PRIVATE 553 * reprocessing, an application can create a reprocessable capture session with 1 input, 554 * ({@code PRIV}, {@code MAXIMUM}), and 3 outputs, ({@code PRIV}, {@code MAXIMUM}), 555 * ({@code PRIV}, {@code PREVIEW}), and ({@code YUV}, {@code MAXIMUM}). However, it's not 556 * guaranteed that an application can submit a regular or reprocess capture with ({@code PRIV}, 557 * {@code MAXIMUM}) and ({@code YUV}, {@code MAXIMUM}) outputs based on the table listed under 558 * {@link #createCaptureSession createCaptureSession}. In other words, use the tables below to 559 * determine the guaranteed stream configurations for creating a reprocessable capture session, 560 * and use the tables under {@link #createCaptureSession createCaptureSession} to determine the 561 * guaranteed output targets that can be submitted in a regular or reprocess 562 * {@link CaptureRequest} simultaneously.</p> 563 * 564 * <style scoped> 565 * #rb { border-right-width: thick; } 566 * </style> 567 * 568 * <p>LIMITED-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 569 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices 570 * support at least the following stream combinations for creating a reprocessable capture 571 * session in addition to those listed in {@link #createCaptureSession createCaptureSession} for 572 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 573 * 574 * <table> 575 * <tr><th colspan="11">LIMITED-level additional guaranteed configurations for creating a reprocessable capture session<br>({@code PRIV} input is guaranteed only if PRIVATE reprocessing is supported. {@code YUV} input is guaranteed only if YUV reprocessing is supported)</th></tr> 576 * <tr><th colspan="2" id="rb">Input</th><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th><th colspan="2" id="rb">Target 4</th><th rowspan="2">Sample use case(s)</th> </tr> 577 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 578 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td></td><td id="rb"></td> <td></td><td id="rb"></td> <td>No-viewfinder still image reprocessing.</td> </tr> 579 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td></td><td id="rb"></td> <td>ZSL(Zero-Shutter-Lag) still imaging.</td> </tr> 580 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td></td><td id="rb"></td> <td>ZSL still and in-app processing imaging.</td> </tr> 581 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>ZSL in-app processing with still capture.</td> </tr> 582 * </table><br> 583 * </p> 584 * 585 * <p>FULL-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 586 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices 587 * support at least the following stream combinations for creating a reprocessable capture 588 * session in addition to those for 589 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 590 * 591 * <table> 592 * <tr><th colspan="11">FULL-level additional guaranteed configurations for creating a reprocessable capture session<br>({@code PRIV} input is guaranteed only if PRIVATE reprocessing is supported. {@code YUV} input is guaranteed only if YUV reprocessing is supported)</th></tr> 593 * <tr><th colspan="2" id="rb">Input</th><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th><th colspan="2" id="rb">Target 4</th><th rowspan="2">Sample use case(s)</th> </tr> 594 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 595 * <tr> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td></td><td id="rb"></td> <td></td><td id="rb"></td> <td>Maximum-resolution multi-frame image fusion in-app processing with regular preview.</td> </tr> 596 * <tr> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td></td><td id="rb"></td> <td></td><td id="rb"></td> <td>Maximum-resolution multi-frame image fusion two-input in-app processing.</td> </tr> 597 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code RECORD}</td> <td></td><td id="rb"></td> <td>High-resolution ZSL in-app video processing with regular preview.</td> </tr> 598 * <tr> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td></td><td id="rb"></td> <td>Maximum-resolution ZSL in-app processing with regular preview.</td> </tr> 599 * <tr> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td></td><td id="rb"></td> <td>Maximum-resolution two-input ZSL in-app processing.</td> </tr> 600 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>ZSL still capture and in-app processing.</td> </tr> 601 * </table><br> 602 * </p> 603 * 604 * <p>RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 605 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support 606 * at least the following stream combinations for creating a reprocessable capture session 607 * on both {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and 608 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices 609 * 610 * <table> 611 * <tr><th colspan="11">RAW-capability additional guaranteed configurations for creating a reprocessable capture session<br>({@code PRIV} input is guaranteed only if PRIVATE reprocessing is supported. {@code YUV} input is guaranteed only if YUV reprocessing is supported)</th></tr> 612 * <tr><th colspan="2" id="rb">Input</th><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th><th colspan="2" id="rb">Target 4</th><th rowspan="2">Sample use case(s)</th> </tr> 613 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 614 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td></td><td id="rb"></td> <td>Mutually exclusive ZSL in-app processing and DNG capture.</td> </tr> 615 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>Mutually exclusive ZSL in-app processing and preview with DNG capture.</td> </tr> 616 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>Mutually exclusive ZSL two-input in-app processing and DNG capture.</td> </tr> 617 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>Mutually exclusive ZSL still capture and preview with DNG capture.</td> </tr> 618 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>Mutually exclusive ZSL in-app processing with still capture and DNG capture.</td> </tr> 619 * </table><br> 620 * </p> 621 * 622 * <p>LEVEL-3 ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 623 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL_3}) devices 624 * support at least the following stream combinations for creating a reprocessable capture 625 * session in addition to those for 626 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} devices. Note that while 627 * the second configuration allows for configuring {@code MAXIMUM} {@code YUV} and {@code JPEG} 628 * outputs at the same time, that configuration is not listed for regular capture sessions, and 629 * therefore simultaneous output to both targets is not allowed. 630 * 631 * <table> 632 * <tr><th colspan="13">LEVEL-3 additional guaranteed configurations for creating a reprocessable capture session<br>({@code PRIV} input is guaranteed only if PRIVATE reprocessing is supported. {@code YUV} input is always guaranteed.</th></tr> 633 * <tr><th colspan="2" id="rb">Input</th><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th><th colspan="2" id="rb">Target 4</th><th colspan="2" id="rb">Target 5</th><th rowspan="2">Sample use case(s)</th> </tr> 634 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 635 * <tr> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code 640x480}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td></td><td id="rb"></td> <td>In-app viewfinder analysis with ZSL and RAW.</td> </tr> 636 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>Same as input</td><td id="rb">{@code MAXIMUM}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code 640x480}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td><td>In-app viewfinder analysis with ZSL, RAW, and JPEG reprocessing output.</td> </tr> 637 * </table><br> 638 * </p> 639 * 640 * <p>Clients can access the above mandatory stream combination tables via 641 * {@link android.hardware.camera2.params.MandatoryStreamCombination}.</p> 642 * 643 * @param inputConfig The configuration for the input {@link Surface} 644 * @param outputs The new set of Surfaces that should be made available as 645 * targets for captured image data. 646 * @param callback The callback to notify about the status of the new capture session. 647 * @param handler The handler on which the callback should be invoked, or {@code null} to use 648 * the current thread's {@link android.os.Looper looper}. 649 * 650 * @throws IllegalArgumentException if the input configuration is null or not supported, the set 651 * of output Surfaces do not meet the requirements, the 652 * callback is null, or the handler is null but the current 653 * thread has no looper. 654 * @throws CameraAccessException if the camera device is no longer connected or has 655 * encountered a fatal error 656 * @throws IllegalStateException if the camera device has been closed 657 * 658 * @see #createCaptureSession 659 * @see CameraCaptureSession 660 * @see StreamConfigurationMap#getInputFormats 661 * @see StreamConfigurationMap#getInputSizes 662 * @see StreamConfigurationMap#getValidOutputFormatsForInput 663 * @see StreamConfigurationMap#getOutputSizes 664 * @see android.media.ImageWriter 665 * @see android.media.ImageReader 666 */ createReprocessableCaptureSession(@onNull InputConfiguration inputConfig, @NonNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)667 public abstract void createReprocessableCaptureSession(@NonNull InputConfiguration inputConfig, 668 @NonNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback, 669 @Nullable Handler handler) 670 throws CameraAccessException; 671 672 /** 673 * Create a new reprocessable camera capture session by providing the desired reprocessing 674 * input configuration and output {@link OutputConfiguration} 675 * to the camera device. 676 * 677 * @see #createReprocessableCaptureSession 678 * @see OutputConfiguration 679 * 680 */ createReprocessableCaptureSessionByConfigurations( @onNull InputConfiguration inputConfig, @NonNull List<OutputConfiguration> outputs, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)681 public abstract void createReprocessableCaptureSessionByConfigurations( 682 @NonNull InputConfiguration inputConfig, 683 @NonNull List<OutputConfiguration> outputs, 684 @NonNull CameraCaptureSession.StateCallback callback, 685 @Nullable Handler handler) 686 throws CameraAccessException; 687 688 /** 689 * <p>Create a new constrained high speed capture session.</p> 690 * 691 * <p>The application can use normal capture session (created via {@link #createCaptureSession}) 692 * for high speed capture if the desired high speed FPS ranges are advertised by 693 * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES}, in which case all API 694 * semantics associated with normal capture sessions applies.</p> 695 * 696 * <p>The method creates a specialized capture session that is only targeted at high speed 697 * video recording (>=120fps) use case if the camera device supports high speed video 698 * capability (i.e., {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} contains 699 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO}). 700 * Therefore, it has special characteristics compared with a normal capture session:</p> 701 * 702 * <ul> 703 * 704 * <li>In addition to the output target Surface requirements specified by the 705 * {@link #createCaptureSession} method, an active high speed capture session will support up 706 * to 2 output Surfaces, though the application might choose to configure just one Surface 707 * (e.g., preview only). All Surfaces must be either video encoder surfaces (acquired by 708 * {@link android.media.MediaRecorder#getSurface} or 709 * {@link android.media.MediaCodec#createInputSurface}) or preview surfaces (obtained from 710 * {@link android.view.SurfaceView}, {@link android.graphics.SurfaceTexture} via 711 * {@link android.view.Surface#Surface(android.graphics.SurfaceTexture)}). The Surface sizes 712 * must be one of the sizes reported by {@link StreamConfigurationMap#getHighSpeedVideoSizes}. 713 * When multiple Surfaces are configured, their size must be same.</li> 714 * 715 * <li>An active high speed capture session only accepts request lists created via 716 * {@link CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList}, and the 717 * request list can only be submitted to this session via 718 * {@link CameraCaptureSession#captureBurst captureBurst}, or 719 * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}.</li> 720 * 721 * <li>The FPS ranges being requested to this session must be selected from 722 * {@link StreamConfigurationMap#getHighSpeedVideoFpsRangesFor}. The application can still use 723 * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE} to control the desired FPS range. 724 * Switching to an FPS range that has different 725 * {@link android.util.Range#getUpper() maximum FPS} may trigger some camera device 726 * reconfigurations, which may introduce extra latency. It is recommended that the 727 * application avoids unnecessary maximum target FPS changes as much as possible during high 728 * speed streaming.</li> 729 * 730 * <li>For the request lists submitted to this session, the camera device will override the 731 * {@link CaptureRequest#CONTROL_MODE control mode}, auto-exposure (AE), auto-white balance 732 * (AWB) and auto-focus (AF) to {@link CameraMetadata#CONTROL_MODE_AUTO}, 733 * {@link CameraMetadata#CONTROL_AE_MODE_ON}, {@link CameraMetadata#CONTROL_AWB_MODE_AUTO} 734 * and {@link CameraMetadata#CONTROL_AF_MODE_CONTINUOUS_VIDEO}, respectively. All 735 * post-processing block mode controls will be overridden to be FAST. Therefore, no manual 736 * control of capture and post-processing parameters is possible. Beside these, only a subset 737 * of controls will work, see 738 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO} for 739 * more details.</li> 740 * 741 * </ul> 742 * 743 * @param outputs The new set of Surfaces that should be made available as 744 * targets for captured high speed image data. 745 * @param callback The callback to notify about the status of the new capture session. 746 * @param handler The handler on which the callback should be invoked, or {@code null} to use 747 * the current thread's {@link android.os.Looper looper}. 748 * 749 * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements, 750 * the callback is null, or the handler is null but the current 751 * thread has no looper, or the camera device doesn't support 752 * high speed video capability. 753 * @throws CameraAccessException if the camera device is no longer connected or has 754 * encountered a fatal error 755 * @throws IllegalStateException if the camera device has been closed 756 * 757 * @see #createCaptureSession 758 * @see CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE 759 * @see StreamConfigurationMap#getHighSpeedVideoSizes 760 * @see StreamConfigurationMap#getHighSpeedVideoFpsRangesFor 761 * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES 762 * @see CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO 763 * @see CameraCaptureSession#captureBurst 764 * @see CameraCaptureSession#setRepeatingBurst 765 * @see CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList 766 */ createConstrainedHighSpeedCaptureSession(@onNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)767 public abstract void createConstrainedHighSpeedCaptureSession(@NonNull List<Surface> outputs, 768 @NonNull CameraCaptureSession.StateCallback callback, 769 @Nullable Handler handler) 770 throws CameraAccessException; 771 772 /** 773 * Standard camera operation mode. 774 * 775 * @see #createCustomCaptureSession 776 * @hide 777 */ 778 @SystemApi 779 @TestApi 780 public static final int SESSION_OPERATION_MODE_NORMAL = 781 0; // ICameraDeviceUser.NORMAL_MODE; 782 783 /** 784 * Constrained high-speed operation mode. 785 * 786 * @see #createCustomCaptureSession 787 * @hide 788 */ 789 @SystemApi 790 @TestApi 791 public static final int SESSION_OPERATION_MODE_CONSTRAINED_HIGH_SPEED = 792 1; // ICameraDeviceUser.CONSTRAINED_HIGH_SPEED_MODE; 793 794 /** 795 * First vendor-specific operating mode 796 * 797 * @see #createCustomCaptureSession 798 * @hide 799 */ 800 @SystemApi 801 @TestApi 802 public static final int SESSION_OPERATION_MODE_VENDOR_START = 803 0x8000; // ICameraDeviceUser.VENDOR_MODE_START; 804 805 /** @hide */ 806 @Retention(RetentionPolicy.SOURCE) 807 @IntDef(prefix = {"SESSION_OPERATION_MODE"}, value = 808 {SESSION_OPERATION_MODE_NORMAL, 809 SESSION_OPERATION_MODE_CONSTRAINED_HIGH_SPEED, 810 SESSION_OPERATION_MODE_VENDOR_START}) 811 public @interface SessionOperatingMode {}; 812 813 /** 814 * Create a new camera capture session with a custom operating mode. 815 * 816 * @param inputConfig The configuration for the input {@link Surface} if a reprocessing session 817 * is desired, or {@code null} otherwise. 818 * @param outputs The new set of {@link OutputConfiguration OutputConfigurations} that should be 819 * made available as targets for captured image data. 820 * @param operatingMode The custom operating mode to use; a nonnegative value, either a custom 821 * vendor value or one of the SESSION_OPERATION_MODE_* values. 822 * @param callback The callback to notify about the status of the new capture session. 823 * @param handler The handler on which the callback should be invoked, or {@code null} to use 824 * the current thread's {@link android.os.Looper looper}. 825 * 826 * @throws IllegalArgumentException if the input configuration is null or not supported, the set 827 * of output Surfaces do not meet the requirements, the 828 * callback is null, or the handler is null but the current 829 * thread has no looper. 830 * @throws CameraAccessException if the camera device is no longer connected or has 831 * encountered a fatal error 832 * @throws IllegalStateException if the camera device has been closed 833 * 834 * @see #createCaptureSession 835 * @see #createReprocessableCaptureSession 836 * @see CameraCaptureSession 837 * @see OutputConfiguration 838 * @hide 839 */ 840 @SystemApi 841 @TestApi createCustomCaptureSession( InputConfiguration inputConfig, @NonNull List<OutputConfiguration> outputs, @SessionOperatingMode int operatingMode, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)842 public abstract void createCustomCaptureSession( 843 InputConfiguration inputConfig, 844 @NonNull List<OutputConfiguration> outputs, 845 @SessionOperatingMode int operatingMode, 846 @NonNull CameraCaptureSession.StateCallback callback, 847 @Nullable Handler handler) 848 throws CameraAccessException; 849 850 /** 851 * <p>Create a new {@link CameraCaptureSession} using a {@link SessionConfiguration} helper 852 * object that aggregates all supported parameters.</p> 853 * 854 * @param config A session configuration (see {@link SessionConfiguration}). 855 * 856 * @throws IllegalArgumentException In case the session configuration is invalid; or the output 857 * configurations are empty; or the session configuration 858 * executor is invalid. 859 * @throws CameraAccessException In case the camera device is no longer connected or has 860 * encountered a fatal error. 861 * @see #createCaptureSession(List, CameraCaptureSession.StateCallback, Handler) 862 * @see #createCaptureSessionByOutputConfigurations 863 * @see #createReprocessableCaptureSession 864 * @see #createConstrainedHighSpeedCaptureSession 865 */ createCaptureSession( SessionConfiguration config)866 public void createCaptureSession( 867 SessionConfiguration config) throws CameraAccessException { 868 throw new UnsupportedOperationException("No default implementation"); 869 } 870 871 /** 872 * <p>Create a {@link CaptureRequest.Builder} for new capture requests, 873 * initialized with template for a target use case. The settings are chosen 874 * to be the best options for the specific camera device, so it is not 875 * recommended to reuse the same request for a different camera device; 876 * create a builder specific for that device and template and override the 877 * settings as desired, instead.</p> 878 * 879 * @param templateType An enumeration selecting the use case for this request. Not all template 880 * types are supported on every device. See the documentation for each template type for 881 * details. 882 * @return a builder for a capture request, initialized with default 883 * settings for that template, and no output streams 884 * 885 * @throws IllegalArgumentException if the templateType is not supported by 886 * this device. 887 * @throws CameraAccessException if the camera device is no longer connected or has 888 * encountered a fatal error 889 * @throws IllegalStateException if the camera device has been closed 890 */ 891 @NonNull createCaptureRequest(@equestTemplate int templateType)892 public abstract CaptureRequest.Builder createCaptureRequest(@RequestTemplate int templateType) 893 throws CameraAccessException; 894 895 /** 896 * <p>Create a {@link CaptureRequest.Builder} for new capture requests, 897 * initialized with template for a target use case. This methods allows 898 * clients to pass physical camera ids which can be used to customize the 899 * request for a specific physical camera. The settings are chosen 900 * to be the best options for the specific logical camera device. If 901 * additional physical camera ids are passed, then they will also use the 902 * same settings template. Clients can further modify individual camera 903 * settings by calling {@link CaptureRequest.Builder#setPhysicalCameraKey}.</p> 904 * 905 * <p>Individual physical camera settings will only be honored for camera session 906 * that was initialiazed with corresponding physical camera id output configuration 907 * {@link OutputConfiguration#setPhysicalCameraId} and the same output targets are 908 * also attached in the request by {@link CaptureRequest.Builder#addTarget}.</p> 909 * 910 * <p>The output is undefined for any logical camera streams in case valid physical camera 911 * settings are attached.</p> 912 * 913 * @param templateType An enumeration selecting the use case for this request. Not all template 914 * types are supported on every device. See the documentation for each template type for 915 * details. 916 * @param physicalCameraIdSet A set of physical camera ids that can be used to customize 917 * the request for a specific physical camera. 918 * @return a builder for a capture request, initialized with default 919 * settings for that template, and no output streams 920 * 921 * @throws IllegalArgumentException if the templateType is not supported by 922 * this device, or one of the physical id arguments matches with logical camera id. 923 * @throws CameraAccessException if the camera device is no longer connected or has 924 * encountered a fatal error 925 * @throws IllegalStateException if the camera device has been closed 926 * 927 * @see #TEMPLATE_PREVIEW 928 * @see #TEMPLATE_RECORD 929 * @see #TEMPLATE_STILL_CAPTURE 930 * @see #TEMPLATE_VIDEO_SNAPSHOT 931 * @see #TEMPLATE_MANUAL 932 * @see CaptureRequest.Builder#setPhysicalCameraKey 933 * @see CaptureRequest.Builder#getPhysicalCameraKey 934 */ 935 @NonNull createCaptureRequest(@equestTemplate int templateType, Set<String> physicalCameraIdSet)936 public CaptureRequest.Builder createCaptureRequest(@RequestTemplate int templateType, 937 Set<String> physicalCameraIdSet) throws CameraAccessException { 938 throw new UnsupportedOperationException("Subclasses must override this method"); 939 } 940 941 /** 942 * <p>Create a {@link CaptureRequest.Builder} for a new reprocess {@link CaptureRequest} from a 943 * {@link TotalCaptureResult}. 944 * 945 * <p>Each reprocess {@link CaptureRequest} processes one buffer from 946 * {@link CameraCaptureSession}'s input {@link Surface} to all output {@link Surface Surfaces} 947 * included in the reprocess capture request. The reprocess input images must be generated from 948 * one or multiple output images captured from the same camera device. The application can 949 * provide input images to camera device via {@link android.media.ImageWriter#queueInputImage}. 950 * The application must use the capture result of one of those output images to create a 951 * reprocess capture request so that the camera device can use the information to achieve 952 * optimal reprocess image quality. For camera devices that support only 1 output 953 * {@link Surface}, submitting a reprocess {@link CaptureRequest} with multiple 954 * output targets will result in a {@link CaptureFailure}. 955 * 956 * @param inputResult The capture result of the output image or one of the output images used 957 * to generate the reprocess input image for this capture request. 958 * 959 * @throws IllegalArgumentException if inputResult is null. 960 * @throws CameraAccessException if the camera device is no longer connected or has 961 * encountered a fatal error 962 * @throws IllegalStateException if the camera device has been closed 963 * 964 * @see CaptureRequest.Builder 965 * @see TotalCaptureResult 966 * @see CameraDevice#createReprocessableCaptureSession 967 * @see android.media.ImageWriter 968 */ 969 @NonNull createReprocessCaptureRequest( @onNull TotalCaptureResult inputResult)970 public abstract CaptureRequest.Builder createReprocessCaptureRequest( 971 @NonNull TotalCaptureResult inputResult) throws CameraAccessException; 972 973 /** 974 * Close the connection to this camera device as quickly as possible. 975 * 976 * <p>Immediately after this call, all calls to the camera device or active session interface 977 * will throw a {@link IllegalStateException}, except for calls to close(). Once the device has 978 * fully shut down, the {@link StateCallback#onClosed} callback will be called, and the camera 979 * is free to be re-opened.</p> 980 * 981 * <p>Immediately after this call, besides the final {@link StateCallback#onClosed} calls, no 982 * further callbacks from the device or the active session will occur, and any remaining 983 * submitted capture requests will be discarded, as if 984 * {@link CameraCaptureSession#abortCaptures} had been called, except that no success or failure 985 * callbacks will be invoked.</p> 986 * 987 */ 988 @Override close()989 public abstract void close(); 990 991 /** 992 * Checks whether a particular {@link SessionConfiguration} is supported by the camera device. 993 * 994 * <p>This method performs a runtime check of a given {@link SessionConfiguration}. The result 995 * confirms whether or not the passed session configuration can be successfully used to 996 * create a camera capture session using 997 * {@link CameraDevice#createCaptureSession(SessionConfiguration)}. 998 * </p> 999 * 1000 * <p>The method can be called at any point before, during and after active capture session. 1001 * It must not impact normal camera behavior in any way and must complete significantly 1002 * faster than creating a regular or constrained capture session.</p> 1003 * 1004 * <p>Although this method is faster than creating a new capture session, it is not intended 1005 * to be used for exploring the entire space of supported stream combinations. The available 1006 * mandatory stream combinations 1007 * {@link android.hardware.camera2.params.MandatoryStreamCombination} are better suited for this 1008 * purpose.</p> 1009 * 1010 * <p>Note that session parameters will be ignored and calls to 1011 * {@link SessionConfiguration#setSessionParameters} are not required.</p> 1012 * 1013 * @return {@code true} if the given session configuration is supported by the camera device 1014 * {@code false} otherwise. 1015 * @throws UnsupportedOperationException if the query operation is not supported by the camera 1016 * device 1017 * @throws IllegalArgumentException if the session configuration is invalid 1018 * @throws CameraAccessException if the camera device is no longer connected or has 1019 * encountered a fatal error 1020 * @throws IllegalStateException if the camera device has been closed 1021 */ isSessionConfigurationSupported( @onNull SessionConfiguration sessionConfig)1022 public boolean isSessionConfigurationSupported( 1023 @NonNull SessionConfiguration sessionConfig) throws CameraAccessException { 1024 throw new UnsupportedOperationException("Subclasses must override this method"); 1025 } 1026 1027 /** 1028 * A callback objects for receiving updates about the state of a camera device. 1029 * 1030 * <p>A callback instance must be provided to the {@link CameraManager#openCamera} method to 1031 * open a camera device.</p> 1032 * 1033 * <p>These state updates include notifications about the device completing startup ( 1034 * allowing for {@link #createCaptureSession} to be called), about device 1035 * disconnection or closure, and about unexpected device errors.</p> 1036 * 1037 * <p>Events about the progress of specific {@link CaptureRequest CaptureRequests} are provided 1038 * through a {@link CameraCaptureSession.CaptureCallback} given to the 1039 * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst}, 1040 * {@link CameraCaptureSession#setRepeatingRequest}, or 1041 * {@link CameraCaptureSession#setRepeatingBurst} methods. 1042 * 1043 * @see CameraManager#openCamera 1044 */ 1045 public static abstract class StateCallback { 1046 /** 1047 * An error code that can be reported by {@link #onError} 1048 * indicating that the camera device is in use already. 1049 * 1050 * <p> 1051 * This error can be produced when opening the camera fails due to the camera 1052 * being used by a higher-priority camera API client. 1053 * </p> 1054 * 1055 * @see #onError 1056 */ 1057 public static final int ERROR_CAMERA_IN_USE = 1; 1058 1059 /** 1060 * An error code that can be reported by {@link #onError} 1061 * indicating that the camera device could not be opened 1062 * because there are too many other open camera devices. 1063 * 1064 * <p> 1065 * The system-wide limit for number of open cameras has been reached, 1066 * and more camera devices cannot be opened until previous instances are 1067 * closed. 1068 * </p> 1069 * 1070 * <p> 1071 * This error can be produced when opening the camera fails. 1072 * </p> 1073 * 1074 * @see #onError 1075 */ 1076 public static final int ERROR_MAX_CAMERAS_IN_USE = 2; 1077 1078 /** 1079 * An error code that can be reported by {@link #onError} 1080 * indicating that the camera device could not be opened due to a device 1081 * policy. 1082 * 1083 * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) 1084 * @see #onError 1085 */ 1086 public static final int ERROR_CAMERA_DISABLED = 3; 1087 1088 /** 1089 * An error code that can be reported by {@link #onError} 1090 * indicating that the camera device has encountered a fatal error. 1091 * 1092 * <p>The camera device needs to be re-opened to be used again.</p> 1093 * 1094 * @see #onError 1095 */ 1096 public static final int ERROR_CAMERA_DEVICE = 4; 1097 1098 /** 1099 * An error code that can be reported by {@link #onError} 1100 * indicating that the camera service has encountered a fatal error. 1101 * 1102 * <p>The Android device may need to be shut down and restarted to restore 1103 * camera function, or there may be a persistent hardware problem.</p> 1104 * 1105 * <p>An attempt at recovery <i>may</i> be possible by closing the 1106 * CameraDevice and the CameraManager, and trying to acquire all resources 1107 * again from scratch.</p> 1108 * 1109 * @see #onError 1110 */ 1111 public static final int ERROR_CAMERA_SERVICE = 5; 1112 1113 /** @hide */ 1114 @Retention(RetentionPolicy.SOURCE) 1115 @IntDef(prefix = {"ERROR_"}, value = 1116 {ERROR_CAMERA_IN_USE, 1117 ERROR_MAX_CAMERAS_IN_USE, 1118 ERROR_CAMERA_DISABLED, 1119 ERROR_CAMERA_DEVICE, 1120 ERROR_CAMERA_SERVICE }) 1121 public @interface ErrorCode {}; 1122 1123 /** 1124 * The method called when a camera device has finished opening. 1125 * 1126 * <p>At this point, the camera device is ready to use, and 1127 * {@link CameraDevice#createCaptureSession} can be called to set up the first capture 1128 * session.</p> 1129 * 1130 * @param camera the camera device that has become opened 1131 */ onOpened(@onNull CameraDevice camera)1132 public abstract void onOpened(@NonNull CameraDevice camera); // Must implement 1133 1134 /** 1135 * The method called when a camera device has been closed with 1136 * {@link CameraDevice#close}. 1137 * 1138 * <p>Any attempt to call methods on this CameraDevice in the 1139 * future will throw a {@link IllegalStateException}.</p> 1140 * 1141 * <p>The default implementation of this method does nothing.</p> 1142 * 1143 * @param camera the camera device that has become closed 1144 */ onClosed(@onNull CameraDevice camera)1145 public void onClosed(@NonNull CameraDevice camera) { 1146 // Default empty implementation 1147 } 1148 1149 /** 1150 * The method called when a camera device is no longer available for 1151 * use. 1152 * 1153 * <p>This callback may be called instead of {@link #onOpened} 1154 * if opening the camera fails.</p> 1155 * 1156 * <p>Any attempt to call methods on this CameraDevice will throw a 1157 * {@link CameraAccessException}. The disconnection could be due to a 1158 * change in security policy or permissions; the physical disconnection 1159 * of a removable camera device; or the camera being needed for a 1160 * higher-priority camera API client.</p> 1161 * 1162 * <p>There may still be capture callbacks that are invoked 1163 * after this method is called, or new image buffers that are delivered 1164 * to active outputs.</p> 1165 * 1166 * <p>The default implementation logs a notice to the system log 1167 * about the disconnection.</p> 1168 * 1169 * <p>You should clean up the camera with {@link CameraDevice#close} after 1170 * this happens, as it is not recoverable until the camera can be opened 1171 * again. For most use cases, this will be when the camera again becomes 1172 * {@link CameraManager.AvailabilityCallback#onCameraAvailable available}. 1173 * </p> 1174 * 1175 * @param camera the device that has been disconnected 1176 */ onDisconnected(@onNull CameraDevice camera)1177 public abstract void onDisconnected(@NonNull CameraDevice camera); // Must implement 1178 1179 /** 1180 * The method called when a camera device has encountered a serious error. 1181 * 1182 * <p>This callback may be called instead of {@link #onOpened} 1183 * if opening the camera fails.</p> 1184 * 1185 * <p>This indicates a failure of the camera device or camera service in 1186 * some way. Any attempt to call methods on this CameraDevice in the 1187 * future will throw a {@link CameraAccessException} with the 1188 * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason. 1189 * </p> 1190 * 1191 * <p>There may still be capture completion or camera stream callbacks 1192 * that will be called after this error is received.</p> 1193 * 1194 * <p>You should clean up the camera with {@link CameraDevice#close} after 1195 * this happens. Further attempts at recovery are error-code specific.</p> 1196 * 1197 * @param camera The device reporting the error 1198 * @param error The error code. 1199 * 1200 * @see #ERROR_CAMERA_IN_USE 1201 * @see #ERROR_MAX_CAMERAS_IN_USE 1202 * @see #ERROR_CAMERA_DISABLED 1203 * @see #ERROR_CAMERA_DEVICE 1204 * @see #ERROR_CAMERA_SERVICE 1205 */ onError(@onNull CameraDevice camera, @ErrorCode int error)1206 public abstract void onError(@NonNull CameraDevice camera, 1207 @ErrorCode int error); // Must implement 1208 } 1209 1210 /** 1211 * To be inherited by android.hardware.camera2.* code only. 1212 * @hide 1213 */ CameraDevice()1214 public CameraDevice() {} 1215 } 1216