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