CameraDevice.java revision 6bbf9dc5ae7ebc85991dcfe3e18e837b12d3f333
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 17package android.hardware.camera2; 18 19import android.view.Surface; 20import android.os.Handler; 21import android.util.Log; 22 23import java.lang.AutoCloseable; 24import java.util.List; 25 26/** 27 * <p>The CameraDevice class is an interface to a single camera connected to an 28 * Android device, allowing for fine-grain control of image capture and 29 * post-processing at high frame rates.</p> 30 * 31 * <p>Your application must declare the 32 * {@link android.Manifest.permission#CAMERA Camera} permission in its manifest 33 * in order to access camera devices.</p> 34 * 35 * <p>A given camera device may provide support at one of two levels: limited or 36 * full. If a device only supports the limited level, then Camera2 exposes a 37 * feature set that is roughly equivalent to the older 38 * {@link android.hardware.Camera Camera} API, although with a cleaner and more 39 * efficient interface. Devices that implement the full level of support 40 * provide substantially improved capabilities over the older camera 41 * API. Applications that target the limited level devices will run unchanged on 42 * the full-level devices; if your application requires a full-level device for 43 * proper operation, declare the "android.hardware.camera2.full" feature in your 44 * manifest.</p> 45 * 46 * @see CameraManager#openCamera 47 * @see android.Manifest.permission#CAMERA 48 */ 49public interface CameraDevice extends AutoCloseable { 50 51 /** 52 * Create a request suitable for a camera preview window. Specifically, this 53 * means that high frame rate is given priority over the highest-quality 54 * post-processing. These requests would normally be used with the 55 * {@link #setRepeatingRequest} method. 56 * 57 * @see #createCaptureRequest 58 */ 59 public static final int TEMPLATE_PREVIEW = 1; 60 61 /** 62 * Create a request suitable for still image capture. Specifically, this 63 * means prioritizing image quality over frame rate. These requests would 64 * commonly be used with the {@link #capture} method. 65 * 66 * @see #createCaptureRequest 67 */ 68 public static final int TEMPLATE_STILL_CAPTURE = 2; 69 70 /** 71 * Create a request suitable for video recording. Specifically, this means 72 * that a stable frame rate is used, and post-processing is set for 73 * recording quality. These requests would commonly be used with the 74 * {@link #setRepeatingRequest} method. 75 * 76 * @see #createCaptureRequest 77 */ 78 public static final int TEMPLATE_RECORD = 3; 79 80 /** 81 * Create a request suitable for still image capture while recording 82 * video. Specifically, this means maximizing image quality without 83 * disrupting the ongoing recording. These requests would commonly be used 84 * with the {@link #capture} method while a request based on 85 * {@link #TEMPLATE_RECORD} is is in use with {@link #setRepeatingRequest}. 86 * 87 * @see #createCaptureRequest 88 */ 89 public static final int TEMPLATE_VIDEO_SNAPSHOT = 4; 90 91 /** 92 * Create a request suitable for zero shutter lag still capture. This means 93 * means maximizing image quality without compromising preview frame rate. 94 * AE/AWB/AF should be on auto mode. 95 * 96 * @see #createCaptureRequest 97 * @hide 98 */ 99 public static final int TEMPLATE_ZERO_SHUTTER_LAG = 5; 100 101 /** 102 * A basic template for direct application control of capture 103 * parameters. All automatic control is disabled (auto-exposure, auto-white 104 * balance, auto-focus), and post-processing parameters are set to preview 105 * quality. The manual capture parameters (exposure, sensitivity, and so on) 106 * are set to reasonable defaults, but should be overriden by the 107 * application depending on the intended use case. 108 * 109 * @see #createCaptureRequest 110 * @hide 111 */ 112 public static final int TEMPLATE_MANUAL = 6; 113 114 /** 115 * Get the ID of this camera device. 116 * 117 * <p>This matches the ID given to {@link CameraManager#openCamera} to instantiate this 118 * this camera device.</p> 119 * 120 * <p>This ID can be used to query the camera device's {@link 121 * CameraProperties fixed properties} with {@link 122 * CameraManager#getCameraProperties}.</p> 123 * 124 * <p>This method can be called even if the device has been closed or has encountered 125 * a serious error.</p> 126 * 127 * @return the ID for this camera device 128 * 129 * @see CameraManager#getCameraProperties 130 * @see CameraManager#getDeviceIdList 131 */ 132 public String getId(); 133 134 /** 135 * Get the static properties for this camera. These are identical to the 136 * properties returned by {@link CameraManager#getCameraProperties}. 137 * 138 * @return the static properties of the camera 139 * 140 * @throws CameraAccessException if the camera device is no longer connected or has 141 * encountered a fatal error 142 * @throws IllegalStateException if the camera device has been closed 143 * 144 * @see CameraManager#getCameraProperties 145 */ 146 public CameraProperties getProperties() throws CameraAccessException; 147 148 /** 149 * <p>Set up a new output set of Surfaces for the camera device.</p> 150 * 151 * <p>The configuration determines the set of potential output Surfaces for 152 * the camera device for each capture request. A given request may use all 153 * or a only some of the outputs. This method must be called before requests 154 * can be submitted to the camera with {@link #capture capture}, 155 * {@link #captureBurst captureBurst}, 156 * {@link #setRepeatingRequest setRepeatingRequest}, or 157 * {@link #setRepeatingBurst setRepeatingBurst}.</p> 158 * 159 * <p>Surfaces suitable for inclusion as a camera output can be created for 160 * various use cases and targets:</p> 161 * 162 * <ul> 163 * 164 * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Set 165 * the size of the Surface with 166 * {@link android.view.SurfaceHolder#setFixedSize} to be one of the 167 * supported 168 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 169 * before calling {@link android.view.SurfaceHolder#getSurface}.</li> 170 * 171 * <li>For accessing through an OpenGL texture via a 172 * {@link android.graphics.SurfaceTexture SurfaceTexture}: Set the size of 173 * the SurfaceTexture with 174 * {@link android.graphics.SurfaceTexture#setDefaultBufferSize} to be one 175 * of the supported 176 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 177 * before creating a Surface from the SurfaceTexture with 178 * {@link Surface#Surface}.</li> 179 * 180 * <li>For recording with {@link android.media.MediaCodec}: Call 181 * {@link android.media.MediaCodec#createInputSurface} after configuring 182 * the media codec to use one of the 183 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 184 * </li> 185 * 186 * <li>For recording with {@link android.media.MediaRecorder}: TODO</li> 187 * 188 * <li>For efficient YUV processing with {@link android.renderscript}: 189 * Create a RenderScript 190 * {@link android.renderscript.Allocation Allocation} with a supported YUV 191 * type, the IO_INPUT flag, and one of the supported 192 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes}. Then 193 * obtain the Surface with 194 * {@link android.renderscript.Allocation#getSurface}.</li> 195 * 196 * <li>For access to uncompressed or JPEG data in the application: Create a 197 * {@link android.media.ImageReader} object with the desired 198 * {@link CameraProperties#SCALER_AVAILABLE_FORMATS image format}, and a 199 * size from the matching 200 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed}, 201 * {@link CameraProperties#SCALER_AVAILABLE_JPEG_SIZES jpeg}. Then obtain 202 * a Surface from it.</li> 203 * 204 * </ul> 205 * 206 * </p> 207 * 208 * <p>This function can take several hundred milliseconds to execute, since 209 * camera hardware may need to be powered on or reconfigured.</p> 210 * 211 * <p>The camera device will query each Surface's size and formats upon this 212 * call, so they must be set to a valid setting at this time (in particular: 213 * if the format is user-visible, it must be one of android.scaler.availableFormats; 214 * and the size must be one of android.scaler.available[Processed|Jpeg]Sizes).</p> 215 * 216 * <p>To change the output, the camera device must be idle. The device is considered 217 * to be idle once all in-flight and pending capture requests have been processed, 218 * and all output image buffers from the captures have been sent to their destination 219 * Surfaces.</p> 220 * 221 * <p>To reach an idle state without cancelling any submitted captures, first 222 * stop any repeating request/burst with {@link #stopRepeating}, and then 223 * wait for the {@link StateListener#onIdle} callback to be 224 * called. To idle as fast as possible, use {@link #flush} and wait for the 225 * idle callback.</p> 226 * 227 * <p>Using larger resolution outputs, or more outputs, can result in slower 228 * output rate from the device.</p> 229 * 230 * <p>Configuring the outputs with an empty or null list will transition 231 * the camera into an {@link StateListener#onUnconfigured unconfigured state}. 232 * </p> 233 * 234 * <p>Calling configureOutputs with the same arguments as the last call to 235 * configureOutputs has no effect.</p> 236 * 237 * @param outputs The new set of Surfaces that should be made available as 238 * targets for captured image data. 239 * 240 * @throws IllegalArgumentException if the set of output Surfaces do not 241 * meet the requirements 242 * @throws CameraAccessException if the camera device is no longer connected or has 243 * encountered a fatal error 244 * @throws IllegalStateException if the camera device is not idle, or 245 * if the camera device has been closed 246 * 247 * @see StateListener#onIdle 248 * @see #stopRepeating 249 * @see #flush 250 */ 251 public void configureOutputs(List<Surface> outputs) throws CameraAccessException; 252 253 /** 254 * <p>Create a {@link CaptureRequest.Builder} for new capture requests, 255 * initialized with template for a target use case. The settings are chosen 256 * to be the best options for the specific camera device, so it is not 257 * recommended to reuse the same request for a different camera device; 258 * create a builder specific for that device and template and override the 259 * settings as desired, instead.</p> 260 * 261 * @param templateType An enumeration selecting the use case for this 262 * request; one of the CameraDevice.TEMPLATE_ values. 263 * @return a builder for a capture request, initialized with default 264 * settings for that template, and no output streams 265 * 266 * @throws IllegalArgumentException if the templateType is not in the list 267 * of supported templates. 268 * @throws CameraAccessException if the camera device is no longer connected or has 269 * encountered a fatal error 270 * @throws IllegalStateException if the camera device has been closed 271 * 272 * @see #TEMPLATE_PREVIEW 273 * @see #TEMPLATE_RECORD 274 * @see #TEMPLATE_STILL_CAPTURE 275 * @see #TEMPLATE_VIDEO_SNAPSHOT 276 * @see #TEMPLATE_MANUAL 277 */ 278 public CaptureRequest.Builder createCaptureRequest(int templateType) 279 throws CameraAccessException; 280 281 /** 282 * <p>Submit a request for an image to be captured by this CameraDevice.</p> 283 * 284 * <p>The request defines all the parameters for capturing the single image, 285 * including sensor, lens, flash, and post-processing settings.</p> 286 * 287 * <p>Each request will produce one {@link CaptureResult} and produce new 288 * frames for one or more target Surfaces, set with the CaptureRequest 289 * builder's {@link CaptureRequest.Builder#addTarget} method. The target 290 * surfaces must be configured as active outputs with 291 * {@link #configureOutputs} before calling this method.</p> 292 * 293 * <p>Multiple requests can be in progress at once. They are processed in 294 * first-in, first-out order, with minimal delays between each 295 * capture. Requests submitted through this method have higher priority than 296 * those submitted through {@link #setRepeatingRequest} or 297 * {@link #setRepeatingBurst}, and will be processed as soon as the current 298 * repeat/repeatBurst processing completes.</p> 299 * 300 * @param request the settings for this capture 301 * @param listener The callback object to notify once this request has been 302 * processed. If null, no metadata will be produced for this capture, 303 * although image data will still be produced. 304 * @param handler the handler on which the listener should be invoked, or 305 * {@code null} to use the current thread's {@link android.os.Looper 306 * looper}. 307 * 308 * @return int A unique capture sequence ID used by 309 * {@link CaptureListener#onCaptureSequenceCompleted}. 310 * 311 * @throws CameraAccessException if the camera device is no longer connected or has 312 * encountered a fatal error 313 * @throws IllegalStateException if the camera is currently busy or unconfigured, 314 * or the camera device has been closed. 315 * @throws IllegalArgumentException If the request targets Surfaces not 316 * currently configured as outputs. Or if the handler is null, the listener 317 * is not null, and the calling thread has no looper. 318 * 319 * @see #captureBurst 320 * @see #setRepeatingRequest 321 * @see #setRepeatingBurst 322 */ 323 public int capture(CaptureRequest request, CaptureListener listener, Handler handler) 324 throws CameraAccessException; 325 326 /** 327 * Submit a list of requests to be captured in sequence as a burst. The 328 * burst will be captured in the minimum amount of time possible, and will 329 * not be interleaved with requests submitted by other capture or repeat 330 * calls. 331 * 332 * <p>The requests will be captured in order, each capture producing one 333 * {@link CaptureResult} and image buffers for one or more target 334 * {@link android.view.Surface surfaces}. The target surfaces for each 335 * request (set with {@link CaptureRequest.Builder#addTarget}) must be 336 * configured as active outputs with {@link #configureOutputs} before 337 * calling this method.</p> 338 * 339 * <p>The main difference between this method and simply calling 340 * {@link #capture} repeatedly is that this method guarantees that no 341 * other requests will be interspersed with the burst.</p> 342 * 343 * @param requests the list of settings for this burst capture 344 * @param listener The callback object to notify each time one of the 345 * requests in the burst has been processed. If null, no metadata will be 346 * produced for any requests in this burst, although image data will still 347 * be produced. 348 * @param handler the handler on which the listener should be invoked, or 349 * {@code null} to use the current thread's {@link android.os.Looper 350 * looper}. 351 * 352 * @return int A unique capture sequence ID used by 353 * {@link CaptureListener#onCaptureSequenceCompleted}. 354 * 355 * @throws CameraAccessException if the camera device is no longer connected or has 356 * encountered a fatal error 357 * @throws IllegalStateException if the camera is currently busy or unconfigured, 358 * or the camera device has been closed. 359 * @throws IllegalArgumentException If the requests target Surfaces not 360 * currently configured as outputs. Or if the handler is null, the listener 361 * is not null, and the calling thread has no looper. 362 * 363 * @see #capture 364 * @see #setRepeatingRequest 365 * @see #setRepeatingBurst 366 */ 367 public int captureBurst(List<CaptureRequest> requests, CaptureListener listener, 368 Handler handler) throws CameraAccessException; 369 370 /** 371 * Request endlessly repeating capture of images by this CameraDevice. 372 * 373 * <p>With this method, the CameraDevice will continually capture images 374 * using the settings in the provided {@link CaptureRequest}, at the maximum 375 * rate possible.</p> 376 * 377 * <p>Repeating requests are a simple way for an application to maintain a 378 * preview or other continuous stream of frames, without having to 379 * continually submit identical requests through {@link #capture}.</p> 380 * 381 * <p>Repeat requests have lower priority than those submitted 382 * through {@link #capture} or {@link #captureBurst}, so if 383 * {@link #capture} is called when a repeating request is active, the 384 * capture request will be processed before any further repeating 385 * requests are processed.<p> 386 * 387 * <p>Repeating requests are a simple way for an application to maintain a 388 * preview or other continuous stream of frames, without having to submit 389 * requests through {@link #capture} at video rates.</p> 390 * 391 * <p>To stop the repeating capture, call {@link #stopRepeating}. Calling 392 * {@link #flush} will also clear the request.</p> 393 * 394 * <p>Calling this method will replace any earlier repeating request or 395 * burst set up by this method or {@link #setRepeatingBurst}, although any 396 * in-progress burst will be completed before the new repeat request will be 397 * used.</p> 398 * 399 * @param request the request to repeat indefinitely 400 * @param listener The callback object to notify every time the 401 * request finishes processing. If null, no metadata will be 402 * produced for this stream of requests, although image data will 403 * still be produced. 404 * @param handler the handler on which the listener should be invoked, or 405 * {@code null} to use the current thread's {@link android.os.Looper 406 * looper}. 407 * 408 * @return int A unique capture sequence ID used by 409 * {@link CaptureListener#onCaptureSequenceCompleted}. 410 * 411 * @throws CameraAccessException if the camera device is no longer connected or has 412 * encountered a fatal error 413 * @throws IllegalStateException if the camera is currently busy or unconfigured, 414 * or the camera device has been closed. 415 * @throws IllegalArgumentException If the requests reference Surfaces not 416 * currently configured as outputs. Or if the handler is null, the listener 417 * is not null, and the calling thread has no looper. 418 * 419 * @see #capture 420 * @see #captureBurst 421 * @see #setRepeatingBurst 422 * @see #stopRepeating 423 * @see #flush 424 */ 425 public int setRepeatingRequest(CaptureRequest request, CaptureListener listener, 426 Handler handler) throws CameraAccessException; 427 428 /** 429 * <p>Request endlessly repeating capture of a sequence of images by this 430 * CameraDevice.</p> 431 * 432 * <p>With this method, the CameraDevice will continually capture images, 433 * cycling through the settings in the provided list of 434 * {@link CaptureRequest CaptureRequests}, at the maximum rate possible.</p> 435 * 436 * <p>If a request is submitted through {@link #capture} or 437 * {@link #captureBurst}, the current repetition of the request list will be 438 * completed before the higher-priority request is handled. This guarantees 439 * that the application always receives a complete repeat burst captured in 440 * minimal time, instead of bursts interleaved with higher-priority 441 * captures, or incomplete captures.</p> 442 * 443 * <p>Repeating burst requests are a simple way for an application to 444 * maintain a preview or other continuous stream of frames where each 445 * request is different in a predicatable way, without having to continually 446 * submit requests through {@link #captureBurst} .</p> 447 * 448 * <p>To stop the repeating capture, call {@link #stopRepeating}. Any 449 * ongoing burst will still be completed, however. Calling 450 * {@link #flush} will also clear the request.</p> 451 * 452 * <p>Calling this method will replace a previously-set repeating request or 453 * burst set up by this method or {@link #setRepeatingRequest}, although any 454 * in-progress burst will be completed before the new repeat burst will be 455 * used.</p> 456 * 457 * @param requests the list of requests to cycle through indefinitely 458 * @param listener The callback object to notify each time one of the 459 * requests in the repeating bursts has finished processing. If null, no 460 * metadata will be produced for this stream of requests, although image 461 * data will still be produced. 462 * @param handler the handler on which the listener should be invoked, or 463 * {@code null} to use the current thread's {@link android.os.Looper 464 * looper}. 465 * 466 * @return int A unique capture sequence ID used by 467 * {@link CaptureListener#onCaptureSequenceCompleted}. 468 * 469 * @throws CameraAccessException if the camera device is no longer connected or has 470 * encountered a fatal error 471 * @throws IllegalStateException if the camera is currently busy or unconfigured, 472 * or the camera device has been closed. 473 * @throws IllegalArgumentException If the requests reference Surfaces not 474 * currently configured as outputs. Or if the handler is null, the listener 475 * is not null, and the calling thread has no looper. 476 * 477 * @see #capture 478 * @see #captureBurst 479 * @see #setRepeatingRequest 480 * @see #stopRepeating 481 * @see #flush 482 */ 483 public int setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener, 484 Handler handler) throws CameraAccessException; 485 486 /** 487 * <p>Cancel any ongoing repeating capture set by either 488 * {@link #setRepeatingRequest setRepeatingRequest} or 489 * {@link #setRepeatingBurst}. Has no effect on requests submitted through 490 * {@link #capture capture} or {@link #captureBurst captureBurst}.</p> 491 * 492 * <p>Any currently in-flight captures will still complete, as will any 493 * burst that is mid-capture. To ensure that the device has finished 494 * processing all of its capture requests and is in idle state, wait for the 495 * {@link StateListener#onIdle} callback after calling this 496 * method..</p> 497 * 498 * @throws CameraAccessException if the camera device is no longer connected or has 499 * encountered a fatal error 500 * @throws IllegalStateException if the camera is currently busy or unconfigured, 501 * or the camera device has been closed. 502 * 503 * @see #setRepeatingRequest 504 * @see #setRepeatingBurst 505 * @see StateListener#onIdle 506 */ 507 public void stopRepeating() throws CameraAccessException; 508 509 /** 510 * <p>Wait until all the submitted requests have finished processing</p> 511 * 512 * <p>This method blocks until all the requests that have been submitted to 513 * the camera device, either through {@link #capture capture}, 514 * {@link #captureBurst captureBurst}, 515 * {@link #setRepeatingRequest setRepeatingRequest}, or 516 * {@link #setRepeatingBurst setRepeatingBurst}, have completed their 517 * processing.</p> 518 * 519 * <p>Once this call returns successfully, the device is in an idle state, 520 * and can be reconfigured with {@link #configureOutputs configureOutputs}.</p> 521 * 522 * <p>This method cannot be used if there is an active repeating request or 523 * burst, set with {@link #setRepeatingRequest setRepeatingRequest} or 524 * {@link #setRepeatingBurst setRepeatingBurst}. Call 525 * {@link #stopRepeating stopRepeating} before calling this method.</p> 526 * 527 * @throws CameraAccessException if the camera device is no longer connected 528 * @throws IllegalStateException if the camera device has been closed, the 529 * device has encountered a fatal error, or if there is an active repeating 530 * request or burst. 531 */ 532 public void waitUntilIdle() throws CameraAccessException; 533 534 /** 535 * Set the listener object to call when an asynchronous device event occurs, 536 * such as errors or idle notifications. 537 * 538 * <p>The events reported here are device-wide; notifications about 539 * individual capture requests or capture results are reported through 540 * {@link CaptureListener}.</p> 541 * 542 * <p>If the camera device is idle when the listener is set, then the 543 * {@link StateListener#onIdle} method will be immediately called, 544 * even if the device has never been active before. 545 * </p> 546 * 547 * @param listener the CameraDeviceListener to send device-level event 548 * notifications to. Setting this to null will stop notifications. 549 * @param handler the handler on which the listener should be invoked, or 550 * {@code null} to use the current thread's {@link android.os.Looper looper}. 551 * 552 * @throws IllegalArgumentException if handler is null, the listener is 553 * not null, and the calling thread has no looper 554 * 555 * @hide 556 */ 557 public void setDeviceListener(StateListener listener, Handler handler); 558 559 /** 560 * Flush all captures currently pending and in-progress as fast as 561 * possible. 562 * 563 * <p>The camera device will discard all of its current work as fast as 564 * possible. Some in-flight captures may complete successfully and call 565 * {@link CaptureListener#onCaptureCompleted}, while others will trigger 566 * their {@link CaptureListener#onCaptureFailed} callbacks. If a repeating 567 * request or a repeating burst is set, it will be cleared by the flush.</p> 568 * 569 * <p>This method is the fastest way to idle the camera device for 570 * reconfiguration with {@link #configureOutputs}, at the cost of discarding 571 * in-progress work. Once the flush is complete, the idle callback will be 572 * called.</p> 573 * 574 * <p>Flushing will introduce at least a brief pause in the stream of data 575 * from the camera device, since once the flush is complete, the first new 576 * request has to make it through the entire camera pipeline before new 577 * output buffers are produced.</p> 578 * 579 * <p>This means that using {@code flush()} to simply remove pending 580 * requests is not recommended; it's best used for quickly switching output 581 * configurations, or for cancelling long in-progress requests (such as a 582 * multi-second capture).</p> 583 * 584 * @throws CameraAccessException if the camera device is no longer connected or has 585 * encountered a fatal error 586 * @throws IllegalStateException if the camera is not idle/active, 587 * or the camera device has been closed. 588 * 589 * @see #setRepeatingRequest 590 * @see #setRepeatingBurst 591 * @see #configureOutputs 592 */ 593 public void flush() throws CameraAccessException; 594 595 /** 596 * Close the connection to this camera device. After this call, all calls to 597 * the camera device interface will throw a {@link IllegalStateException}, 598 * except for calls to close(). 599 */ 600 @Override 601 public void close(); 602 // TODO: We should decide on the behavior of in-flight requests should be on close. 603 604 /** 605 * <p>A listener for tracking the progress of a {@link CaptureRequest} 606 * submitted to the camera device.</p> 607 * 608 * <p>This listener is called when a request triggers a capture to start, 609 * and when the capture is complete. In case on an error capturing an image, 610 * the error method is triggered instead of the completion method.</p> 611 * 612 * @see #capture 613 * @see #captureBurst 614 * @see #setRepeatingRequest 615 * @see #setRepeatingBurst 616 */ 617 public static abstract class CaptureListener { 618 619 /** 620 * This method is called when the camera device has started capturing 621 * the output image for the request, at the beginning of image exposure. 622 * 623 * <p>This callback is invoked right as the capture of a frame begins, 624 * so it is the most appropriate time for playing a shutter sound, 625 * or triggering UI indicators of capture.</p> 626 * 627 * <p>The request that is being used for this capture is provided, along 628 * with the actual timestamp for the start of exposure. This timestamp 629 * matches the timestamp that will be included in 630 * {@link CaptureResult#SENSOR_TIMESTAMP the result timestamp field}, 631 * and in the buffers sent to each output Surface. These buffer 632 * timestamps are accessible through, for example, 633 * {@link android.media.Image#getTimestamp() Image.getTimestamp()} or 634 * {@link android.graphics.SurfaceTexture#getTimestamp()}.</p> 635 * 636 * <p>For the simplest way to play a shutter sound camera shutter or a 637 * video recording start/stop sound, see the 638 * {@link android.media.MediaActionSound} class.</p> 639 * 640 * <p>The default implementation of this method does nothing.</p> 641 * 642 * @param camera the CameraDevice sending the callback 643 * @param request the request for the capture that just begun 644 * @param timestamp the timestamp at start of capture, in nanoseconds. 645 * 646 * @see android.media.MediaActionSound 647 */ 648 public void onCaptureStarted(CameraDevice camera, 649 CaptureRequest request, long timestamp) { 650 // default empty implementation 651 } 652 653 /** 654 * This method is called when an image capture has completed and the 655 * result metadata is available. 656 * 657 * <p>The default implementation of this method does nothing.</p> 658 * 659 * @param camera The CameraDevice sending the callback. 660 * @param request The request that was given to the CameraDevice 661 * @param result The output metadata from the capture, including the 662 * final capture parameters and the state of the camera system during 663 * capture. 664 * 665 * @see #capture 666 * @see #captureBurst 667 * @see #setRepeatingRequest 668 * @see #setRepeatingBurst 669 */ 670 public void onCaptureCompleted(CameraDevice camera, 671 CaptureRequest request, CaptureResult result) { 672 // default empty implementation 673 } 674 675 /** 676 * This method is called instead of {@link #onCaptureCompleted} when the 677 * camera device failed to produce a {@link CaptureResult} for the 678 * request. 679 * 680 * <p>Other requests are unaffected, and some or all image buffers from 681 * the capture may have been pushed to their respective output 682 * streams.</p> 683 * 684 * <p>The default implementation of this method does nothing.</p> 685 * 686 * @param camera 687 * The CameraDevice sending the callback. 688 * @param request 689 * The request that was given to the CameraDevice 690 * @param failure 691 * The output failure from the capture, including the failure reason 692 * and the frame number. 693 * 694 * @see #capture 695 * @see #captureBurst 696 * @see #setRepeatingRequest 697 * @see #setRepeatingBurst 698 */ 699 public void onCaptureFailed(CameraDevice camera, 700 CaptureRequest request, CaptureFailure failure) { 701 // default empty implementation 702 } 703 704 /** 705 * This method is called independently of the others in CaptureListener, 706 * when a capture sequence finishes and all {@link CaptureResult} 707 * or {@link CaptureFailure} for it have been returned via this listener. 708 * 709 * @param camera 710 * The CameraDevice sending the callback. 711 * @param sequenceId 712 * A sequence ID returned by the {@link #capture} family of functions. 713 * @param frameNumber 714 * The last frame number (returned by {@link CaptureResult#getFrameNumber} 715 * or {@link CaptureFailure#getFrameNumber}) in the capture sequence. 716 * 717 * @see CaptureResult#getFrameNumber() 718 * @see CaptureFailure#getFrameNumber() 719 * @see CaptureResult#getSequenceId() 720 * @see CaptureFailure#getSequenceId() 721 */ 722 public void onCaptureSequenceCompleted(CameraDevice camera, 723 int sequenceId, int frameNumber) { 724 // default empty implementation 725 } 726 } 727 728 /** 729 * A listener for notifications about the state of a camera 730 * device. 731 * 732 * <p>These events include notifications about the device becoming idle ( 733 * allowing for {@link #configureOutputs} to be called), about device 734 * disconnection, and about unexpected device errors.</p> 735 * 736 * <p>Events about the progress of specific {@link CaptureRequest 737 * CaptureRequests} are provided through a {@link CaptureListener} given to 738 * the {@link #capture}, {@link #captureBurst}, {@link 739 * #setRepeatingRequest}, or {@link #setRepeatingBurst} methods. 740 * 741 * @see #setDeviceListener 742 */ 743 public static abstract class StateListener { 744 /** 745 * An error code that can be reported by {@link #onError} 746 * indicating that the camera device is in use already. 747 * 748 * <p> 749 * This error can be produced when opening the camera fails. 750 * </p> 751 * 752 * @see #onError 753 */ 754 public static final int ERROR_CAMERA_IN_USE = 1; 755 756 /** 757 * An error code that can be reported by {@link #onError} 758 * indicating that the camera device could not be opened 759 * because there are too many other open camera devices. 760 * 761 * <p> 762 * The system-wide limit for number of open cameras has been reached, 763 * and more camera devices cannot be opened until previous instances are 764 * closed. 765 * </p> 766 * 767 * <p> 768 * This error can be produced when opening the camera fails. 769 * </p> 770 * 771 * @see #onError 772 */ 773 public static final int ERROR_MAX_CAMERAS_IN_USE = 2; 774 775 /** 776 * An error code that can be reported by {@link #onError} 777 * indicating that the camera device could not be opened due to a device 778 * policy. 779 * 780 * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) 781 * @see #onError 782 */ 783 public static final int ERROR_CAMERA_DISABLED = 3; 784 785 /** 786 * An error code that can be reported by {@link #onError} 787 * indicating that the camera device has encountered a fatal error. 788 * 789 * <p>The camera device needs to be re-opened to be used again.</p> 790 * 791 * @see #onError 792 */ 793 public static final int ERROR_CAMERA_DEVICE = 4; 794 795 /** 796 * An error code that can be reported by {@link #onError} 797 * indicating that the camera service has encountered a fatal error. 798 * 799 * <p>The Android device may need to be shut down and restarted to restore 800 * camera function, or there may be a persistent hardware problem.</p> 801 * 802 * <p>An attempt at recovery <i>may</i> be possible by closing the 803 * CameraDevice and the CameraManager, and trying to acquire all resources 804 * again from scratch.</p> 805 * 806 * @see #onError 807 */ 808 public static final int ERROR_CAMERA_SERVICE = 5; 809 810 /** 811 * The method called when a camera device has finished opening. 812 * 813 * <p>An opened camera will immediately afterwards transition into 814 * {@link #onUnconfigured}.</p> 815 * 816 * @param camera the camera device that has become opened 817 */ 818 public abstract void onOpened(CameraDevice camera); // Must implement 819 820 /** 821 * The method called when a camera device has no outputs configured. 822 * 823 * <p>An unconfigured camera device needs to be configured with 824 * {@link CameraDevice#configureOutputs} before being able to 825 * submit any capture request.</p> 826 * 827 * <p>This state may be entered by a newly opened camera or by 828 * calling {@link CameraDevice#configureOutputs} with a null/empty 829 * list of Surfaces when idle.</p> 830 * 831 * <p>Any attempts to submit a capture request while in this state 832 * will result in an {@link IllegalStateException} being thrown.</p> 833 * 834 * <p>The default implementation of this method does nothing.</p> 835 * 836 * @param camera the camera device has that become unconfigured 837 */ 838 public void onUnconfigured(CameraDevice camera) { 839 // Default empty implementation 840 } 841 842 /** 843 * The method called when a camera device begins processing 844 * {@link CaptureRequest capture requests}. 845 * 846 * <p>A camera may not be re-configured while in this state. The camera 847 * will transition to the idle state once all pending captures have 848 * completed. If a repeating request is set, the camera will remain active 849 * until it is cleared and the remaining requests finish processing. To 850 * transition to the idle state as quickly as possible, call {@link #flush()}, 851 * which will idle the camera device as quickly as possible, likely canceling 852 * most in-progress captures.</p> 853 * 854 * <p>All calls except for {@link CameraDevice#configureOutputs} are 855 * legal while in this state. 856 * </p> 857 * 858 * <p>The default implementation of this method does nothing.</p> 859 * 860 * @param camera the camera device that has become active 861 * 862 * @see CameraDevice#capture 863 * @see CameraDevice#captureBurst 864 * @see CameraDevice#setRepeatingBurst 865 * @see CameraDevice#setRepeatingRequest 866 */ 867 public void onActive(CameraDevice camera) { 868 // Default empty implementation 869 } 870 871 /** 872 * The method called when a camera device is busy. 873 * 874 * <p>A camera becomes busy while it's outputs are being configured 875 * (after a call to {@link CameraDevice#configureOutputs} or while it's 876 * being flushed (after a call to {@link CameraDevice#flush}.</p> 877 * 878 * <p>Once the on-going operations are complete, the camera will automatically 879 * transition into {@link #onIdle} if there is at least one configured output, 880 * or {@link #onUnconfigured} otherwise.</p> 881 * 882 * <p>Any attempts to manipulate the camera while its is busy 883 * will result in an {@link IllegalStateException} being thrown.</p> 884 * 885 * <p>Only the following methods are valid to call while in this state: 886 * <ul> 887 * <li>{@link CameraDevice#getId}</li> 888 * <li>{@link CameraDevice#createCaptureRequest}</li> 889 * <li>{@link CameraDevice#close}</li> 890 * </ul> 891 * </p> 892 * 893 * <p>The default implementation of this method does nothing.</p> 894 * 895 * @param camera the camera device that has become busy 896 * 897 * @see CameraDevice#configureOutputs 898 * @see CameraDevice#flush 899 */ 900 public void onBusy(CameraDevice camera) { 901 // Default empty implementation 902 } 903 904 /** 905 * The method called when a camera device has been closed with 906 * {@link CameraDevice#close}. 907 * 908 * <p>Any attempt to call methods on this CameraDevice in the 909 * future will throw a {@link IllegalStateException}.</p> 910 * 911 * <p>The default implementation of this method does nothing.</p> 912 * 913 * @param camera the camera device that has become closed 914 */ 915 public void onClosed(CameraDevice camera) { 916 // Default empty implementation 917 } 918 919 /** 920 * The method called when a camera device has finished processing all 921 * submitted capture requests and has reached an idle state. 922 * 923 * <p>An idle camera device can have its outputs changed by calling {@link 924 * CameraDevice#configureOutputs}, which will transition it into the busy state.</p> 925 * 926 * <p>To idle and reconfigure outputs without canceling any submitted 927 * capture requests, the application needs to clear its repeating 928 * request/burst, if set, with {@link CameraDevice#stopRepeating}, and 929 * then wait for this callback to be called before calling {@link 930 * CameraDevice#configureOutputs}.</p> 931 * 932 * <p>To idle and reconfigure a camera device as fast as possible, the 933 * {@link CameraDevice#flush} method can be used, which will discard all 934 * pending and in-progress capture requests. Once the {@link 935 * CameraDevice#flush} method is called, the application must wait for 936 * this callback to fire before calling {@link 937 * CameraDevice#configureOutputs}.</p> 938 * 939 * <p>The default implementation of this method does nothing.</p> 940 * 941 * @param camera the camera device that has become idle 942 * 943 * @see CameraDevice#configureOutputs 944 * @see CameraDevice#stopRepeating 945 * @see CameraDevice#flush 946 */ 947 public void onIdle(CameraDevice camera) { 948 // Default empty implementation 949 } 950 951 /** 952 * The method called when a camera device is no longer available for 953 * use. 954 * 955 * <p>This callback may be called instead of {@link #onOpened} 956 * if opening the camera fails.</p> 957 * 958 * <p>Any attempt to call methods on this CameraDevice will throw a 959 * {@link CameraAccessException}. The disconnection could be due to a 960 * change in security policy or permissions; the physical disconnection 961 * of a removable camera device; or the camera being needed for a 962 * higher-priority use case.</p> 963 * 964 * <p>There may still be capture listener callbacks that are called 965 * after this method is called, or new image buffers that are delivered 966 * to active outputs.</p> 967 * 968 * <p>The default implementation logs a notice to the system log 969 * about the disconnection.</p> 970 * 971 * <p>You should clean up the camera with {@link CameraDevice#close} after 972 * this happens, as it is not recoverable until opening the camera again 973 * after it becomes {@link CameraManager.AvailabilityListener#onCameraAvailable available}. 974 * </p> 975 * 976 * @param camera the device that has been disconnected 977 */ 978 public abstract void onDisconnected(CameraDevice camera); // Must implement 979 980 /** 981 * The method called when a camera device has encountered a serious error. 982 * 983 * <p>This callback may be called instead of {@link #onOpened} 984 * if opening the camera fails.</p> 985 * 986 * <p>This indicates a failure of the camera device or camera service in 987 * some way. Any attempt to call methods on this CameraDevice in the 988 * future will throw a {@link CameraAccessException} with the 989 * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason. 990 * </p> 991 * 992 * <p>There may still be capture completion or camera stream listeners 993 * that will be called after this error is received.</p> 994 * 995 * <p>You should clean up the camera with {@link CameraDevice#close} after 996 * this happens. Further attempts at recovery are error-code specific.</p> 997 * 998 * @param camera The device reporting the error 999 * @param error The error code, one of the 1000 * {@code CameraDeviceListener.ERROR_*} values. 1001 * 1002 * @see #ERROR_CAMERA_DEVICE 1003 * @see #ERROR_CAMERA_SERVICE 1004 * @see #ERROR_CAMERA_DISABLED 1005 * @see #ERROR_CAMERA_IN_USE 1006 */ 1007 public abstract void onError(CameraDevice camera, int error); // Must implement 1008 } 1009} 1010