CameraCaptureSession.java revision fd887436bd111e4d2c7307578a51b5070025b7f2
1/* 2 * Copyright (C) 2014 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.os.Handler; 20import java.util.List; 21 22/** 23 * A configured capture session for a {@link CameraDevice}, used for capturing 24 * images from the camera. 25 * 26 * <p>A CameraCaptureSession is created by providing a set of target output surfaces to 27 * {@link CameraDevice#createCaptureSession createCaptureSession}. Once created, the session is 28 * active until a new session is created by the camera device, or the camera device is closed.</p> 29 * 30 * <p>Creating a session is an expensive operation and can take several hundred milliseconds, since 31 * it requires configuring the camera device's internal pipelines and allocating memory buffers for 32 * sending images to the desired targets. Therefore the setup is done asynchronously, and 33 * {@link CameraDevice#createCaptureSession createCaptureSession} will send the ready-to-use 34 * CameraCaptureSession to the provided listener's 35 * {@link CameraCaptureSession.StateCallback#onConfigured onConfigured} callback. If configuration 36 * cannot be completed, then the 37 * {@link CameraCaptureSession.StateCallback#onConfigureFailed onConfigureFailed} is called, and the 38 * session will not become active.</p> 39 *<!-- 40 * <p>Any capture requests (repeating or non-repeating) submitted before the session is ready will 41 * be queued up and will begin capture once the session becomes ready. In case the session cannot be 42 * configured and {@link StateCallback#onConfigureFailed onConfigureFailed} is called, all queued 43 * capture requests are discarded.</p> 44 *--> 45 * <p>If a new session is created by the camera device, then the previous session is closed, and its 46 * associated {@link StateCallback#onClosed onClosed} callback will be invoked. All 47 * of the session methods will throw an IllegalStateException if called once the session is 48 * closed.</p> 49 * 50 * <p>A closed session clears any repeating requests (as if {@link #stopRepeating} had been called), 51 * but will still complete all of its in-progress capture requests as normal, before a newly 52 * created session takes over and reconfigures the camera device.</p> 53 */ 54public abstract class CameraCaptureSession implements AutoCloseable { 55 56 /** 57 * Get the camera device that this session is created for. 58 */ 59 public abstract CameraDevice getDevice(); 60 61 /** 62 * <p>Submit a request for an image to be captured by the camera device.</p> 63 * 64 * <p>The request defines all the parameters for capturing the single image, 65 * including sensor, lens, flash, and post-processing settings.</p> 66 * 67 * <p>Each request will produce one {@link CaptureResult} and produce new frames for one or more 68 * target Surfaces, set with the CaptureRequest builder's 69 * {@link CaptureRequest.Builder#addTarget} method. The target surfaces (set with 70 * {@link CaptureRequest.Builder#addTarget}) must be a subset of the surfaces provided when this 71 * capture session was created.</p> 72 * 73 * <p>Multiple requests can be in progress at once. They are processed in 74 * first-in, first-out order, with minimal delays between each 75 * capture. Requests submitted through this method have higher priority than 76 * those submitted through {@link #setRepeatingRequest} or 77 * {@link #setRepeatingBurst}, and will be processed as soon as the current 78 * repeat/repeatBurst processing completes.</p> 79 * 80 * @param request the settings for this capture 81 * @param listener The callback object to notify once this request has been 82 * processed. If null, no metadata will be produced for this capture, 83 * although image data will still be produced. 84 * @param handler the handler on which the listener should be invoked, or 85 * {@code null} to use the current thread's {@link android.os.Looper 86 * looper}. 87 * 88 * @return int A unique capture sequence ID used by 89 * {@link CaptureCallback#onCaptureSequenceCompleted}. 90 * 91 * @throws CameraAccessException if the camera device is no longer connected or has 92 * encountered a fatal error 93 * @throws IllegalStateException if this session is no longer active, either because the session 94 * was explicitly closed, a new session has been created 95 * or the camera device has been closed. 96 * @throws IllegalArgumentException if the request targets no Surfaces or Surfaces that are not 97 * configured as outputs for this session. Or if the handler is 98 * null, the listener is not null, and the calling thread has 99 * no looper. 100 * 101 * @see #captureBurst 102 * @see #setRepeatingRequest 103 * @see #setRepeatingBurst 104 * @see #abortCaptures 105 */ 106 public abstract int capture(CaptureRequest request, CaptureCallback listener, Handler handler) 107 throws CameraAccessException; 108 109 /** 110 * Submit a list of requests to be captured in sequence as a burst. The 111 * burst will be captured in the minimum amount of time possible, and will 112 * not be interleaved with requests submitted by other capture or repeat 113 * calls. 114 * 115 * <p>The requests will be captured in order, each capture producing one {@link CaptureResult} 116 * and image buffers for one or more target {@link android.view.Surface surfaces}. The target 117 * surfaces (set with {@link CaptureRequest.Builder#addTarget}) must be a subset of the surfaces 118 * provided when this capture session was created.</p> 119 * 120 * <p>The main difference between this method and simply calling 121 * {@link #capture} repeatedly is that this method guarantees that no 122 * other requests will be interspersed with the burst.</p> 123 * 124 * @param requests the list of settings for this burst capture 125 * @param listener The callback object to notify each time one of the 126 * requests in the burst has been processed. If null, no metadata will be 127 * produced for any requests in this burst, although image data will still 128 * be produced. 129 * @param handler the handler on which the listener should be invoked, or 130 * {@code null} to use the current thread's {@link android.os.Looper 131 * looper}. 132 * 133 * @return int A unique capture sequence ID used by 134 * {@link CaptureCallback#onCaptureSequenceCompleted}. 135 * 136 * @throws CameraAccessException if the camera device is no longer connected or has 137 * encountered a fatal error 138 * @throws IllegalStateException if this session is no longer active, either because the session 139 * was explicitly closed, a new session has been created 140 * or the camera device has been closed. 141 * @throws IllegalArgumentException If the requests target no Surfaces or Surfaces not currently 142 * configured as outputs. Or if the handler is null, the 143 * listener is not null, and the calling thread has no looper. 144 * 145 * @see #capture 146 * @see #setRepeatingRequest 147 * @see #setRepeatingBurst 148 * @see #abortCaptures 149 */ 150 public abstract int captureBurst(List<CaptureRequest> requests, CaptureCallback listener, 151 Handler handler) throws CameraAccessException; 152 153 /** 154 * Request endlessly repeating capture of images by this capture session. 155 * 156 * <p>With this method, the camera device will continually capture images 157 * using the settings in the provided {@link CaptureRequest}, at the maximum 158 * rate possible.</p> 159 * 160 * <p>Repeating requests are a simple way for an application to maintain a 161 * preview or other continuous stream of frames, without having to 162 * continually submit identical requests through {@link #capture}.</p> 163 * 164 * <p>Repeat requests have lower priority than those submitted 165 * through {@link #capture} or {@link #captureBurst}, so if 166 * {@link #capture} is called when a repeating request is active, the 167 * capture request will be processed before any further repeating 168 * requests are processed.<p> 169 * 170 * <p>To stop the repeating capture, call {@link #stopRepeating}. Calling 171 * {@link #abortCaptures} will also clear the request.</p> 172 * 173 * <p>Calling this method will replace any earlier repeating request or 174 * burst set up by this method or {@link #setRepeatingBurst}, although any 175 * in-progress burst will be completed before the new repeat request will be 176 * used.</p> 177 * 178 * @param request the request to repeat indefinitely 179 * @param listener The callback object to notify every time the 180 * request finishes processing. If null, no metadata will be 181 * produced for this stream of requests, although image data will 182 * still be produced. 183 * @param handler the handler on which the listener should be invoked, or 184 * {@code null} to use the current thread's {@link android.os.Looper 185 * looper}. 186 * 187 * @return int A unique capture sequence ID used by 188 * {@link CaptureCallback#onCaptureSequenceCompleted}. 189 * 190 * @throws CameraAccessException if the camera device is no longer connected or has 191 * encountered a fatal error 192 * @throws IllegalStateException if this session is no longer active, either because the session 193 * was explicitly closed, a new session has been created 194 * or the camera device has been closed. 195 * @throws IllegalArgumentException If the requests reference no Surfaces or Surfaces that are 196 * not currently configured as outputs. Or if the handler is 197 * null, the listener is not null, and the calling thread has 198 * no looper. Or if no requests were passed in. 199 * 200 * @see #capture 201 * @see #captureBurst 202 * @see #setRepeatingBurst 203 * @see #stopRepeating 204 * @see #abortCaptures 205 */ 206 public abstract int setRepeatingRequest(CaptureRequest request, CaptureCallback listener, 207 Handler handler) throws CameraAccessException; 208 209 /** 210 * <p>Request endlessly repeating capture of a sequence of images by this 211 * capture session.</p> 212 * 213 * <p>With this method, the camera device will continually capture images, 214 * cycling through the settings in the provided list of 215 * {@link CaptureRequest CaptureRequests}, at the maximum rate possible.</p> 216 * 217 * <p>If a request is submitted through {@link #capture} or 218 * {@link #captureBurst}, the current repetition of the request list will be 219 * completed before the higher-priority request is handled. This guarantees 220 * that the application always receives a complete repeat burst captured in 221 * minimal time, instead of bursts interleaved with higher-priority 222 * captures, or incomplete captures.</p> 223 * 224 * <p>Repeating burst requests are a simple way for an application to 225 * maintain a preview or other continuous stream of frames where each 226 * request is different in a predicatable way, without having to continually 227 * submit requests through {@link #captureBurst}.</p> 228 * 229 * <p>To stop the repeating capture, call {@link #stopRepeating}. Any 230 * ongoing burst will still be completed, however. Calling 231 * {@link #abortCaptures} will also clear the request.</p> 232 * 233 * <p>Calling this method will replace a previously-set repeating request or 234 * burst set up by this method or {@link #setRepeatingRequest}, although any 235 * in-progress burst will be completed before the new repeat burst will be 236 * used.</p> 237 * 238 * @param requests the list of requests to cycle through indefinitely 239 * @param listener The callback object to notify each time one of the 240 * requests in the repeating bursts has finished processing. If null, no 241 * metadata will be produced for this stream of requests, although image 242 * data will still be produced. 243 * @param handler the handler on which the listener should be invoked, or 244 * {@code null} to use the current thread's {@link android.os.Looper 245 * looper}. 246 * 247 * @return int A unique capture sequence ID used by 248 * {@link CaptureCallback#onCaptureSequenceCompleted}. 249 * 250 * @throws CameraAccessException if the camera device is no longer connected or has 251 * encountered a fatal error 252 * @throws IllegalStateException if this session is no longer active, either because the session 253 * was explicitly closed, a new session has been created 254 * or the camera device has been closed. 255 * @throws IllegalArgumentException If the requests reference no Surfaces or Surfaces not 256 * currently configured as outputs. Or if the handler is null, 257 * the listener is not null, and the calling thread has no 258 * looper. Or if no requests were passed in. 259 * 260 * @see #capture 261 * @see #captureBurst 262 * @see #setRepeatingRequest 263 * @see #stopRepeating 264 * @see #abortCaptures 265 */ 266 public abstract int setRepeatingBurst(List<CaptureRequest> requests, CaptureCallback listener, 267 Handler handler) throws CameraAccessException; 268 269 /** 270 * <p>Cancel any ongoing repeating capture set by either 271 * {@link #setRepeatingRequest setRepeatingRequest} or 272 * {@link #setRepeatingBurst}. Has no effect on requests submitted through 273 * {@link #capture capture} or {@link #captureBurst captureBurst}.</p> 274 * 275 * <p>Any currently in-flight captures will still complete, as will any burst that is 276 * mid-capture. To ensure that the device has finished processing all of its capture requests 277 * and is in ready state, wait for the {@link StateCallback#onReady} callback after 278 * calling this method.</p> 279 * 280 * @throws CameraAccessException if the camera device is no longer connected or has 281 * encountered a fatal error 282 * @throws IllegalStateException if this session is no longer active, either because the session 283 * was explicitly closed, a new session has been created 284 * or the camera device has been closed. 285 * 286 * @see #setRepeatingRequest 287 * @see #setRepeatingBurst 288 * @see StateCallback#onIdle 289 */ 290 public abstract void stopRepeating() throws CameraAccessException; 291 292 /** 293 * Discard all captures currently pending and in-progress as fast as possible. 294 * 295 * <p>The camera device will discard all of its current work as fast as possible. Some in-flight 296 * captures may complete successfully and call {@link CaptureCallback#onCaptureCompleted}, while 297 * others will trigger their {@link CaptureCallback#onCaptureFailed} callbacks. If a repeating 298 * request or a repeating burst is set, it will be cleared.</p> 299 * 300 * <p>This method is the fastest way to switch the camera device to a new session with 301 * {@link CameraDevice#createCaptureSession}, at the cost of discarding in-progress work. It 302 * must be called before the new session is created. Once all pending requests are either 303 * completed or thrown away, the {@link StateCallback#onReady} callback will be called, 304 * if the session has not been closed. Otherwise, the {@link StateCallback#onClosed} 305 * callback will be fired when a new session is created by the camera device.</p> 306 * 307 * <p>Cancelling will introduce at least a brief pause in the stream of data from the camera 308 * device, since once the camera device is emptied, the first new request has to make it through 309 * the entire camera pipeline before new output buffers are produced.</p> 310 * 311 * <p>This means that using {@code abortCaptures()} to simply remove pending requests is not 312 * recommended; it's best used for quickly switching output configurations, or for cancelling 313 * long in-progress requests (such as a multi-second capture).</p> 314 * 315 * @throws CameraAccessException if the camera device is no longer connected or has 316 * encountered a fatal error 317 * @throws IllegalStateException if this session is no longer active, either because the session 318 * was explicitly closed, a new session has been created 319 * or the camera device has been closed. 320 * 321 * @see #setRepeatingRequest 322 * @see #setRepeatingBurst 323 * @see CameraDevice#createCaptureSession 324 */ 325 public abstract void abortCaptures() throws CameraAccessException; 326 327 /** 328 * Close this capture session asynchronously. 329 * 330 * <p>Closing a session frees up the target output Surfaces of the session for reuse with either 331 * a new session, or to other APIs that can draw to Surfaces.</p> 332 * 333 * <p>Note that creating a new capture session with {@link CameraDevice#createCaptureSession} 334 * will close any existing capture session automatically, and call the older session listener's 335 * {@link StateCallback#onClosed} callback. Using {@link CameraDevice#createCaptureSession} 336 * directly without closing is the recommended approach for quickly switching to a new session, 337 * since unchanged target outputs can be reused more efficiently.</p> 338 * 339 * <p>Once a session is closed, all methods on it will throw an IllegalStateException, and any 340 * repeating requests or bursts are stopped (as if {@link #stopRepeating()} was called). 341 * However, any in-progress capture requests submitted to the session will be completed as 342 * normal; once all captures have completed and the session has been torn down, 343 * {@link StateCallback#onClosed} will be called.</p> 344 * 345 * <p>Closing a session is idempotent; closing more than once has no effect.</p> 346 */ 347 @Override 348 public abstract void close(); 349 350 /** 351 * A callback object for receiving updates about the state of a camera capture session. 352 * 353 */ 354 public static abstract class StateCallback { 355 356 /** 357 * This method is called when the camera device has finished configuring itself, and the 358 * session can start processing capture requests. 359 * 360 * <p>If there are capture requests already queued with the session, they will start 361 * processing once this callback is invoked, and the session will call {@link #onActive} 362 * right after this callback is invoked.</p> 363 * 364 * <p>If no capture requests have been submitted, then the session will invoke 365 * {@link #onReady} right after this callback.</p> 366 * 367 * <p>If the camera device configuration fails, then {@link #onConfigureFailed} will 368 * be invoked instead of this callback.</p> 369 * 370 * @param session the session returned by {@link CameraDevice#createCaptureSession} 371 */ 372 public abstract void onConfigured(CameraCaptureSession session); 373 374 /** 375 * This method is called if the session cannot be configured as requested. 376 * 377 * <p>This can happen if the set of requested outputs contains unsupported sizes, 378 * or too many outputs are requested at once.</p> 379 * 380 * <p>The session is considered to be closed, and all methods called on it after this 381 * callback is invoked will throw an IllegalStateException. Any capture requests submitted 382 * to the session prior to this callback will be discarded and will not produce any 383 * callbacks on their listeners.</p> 384 * 385 * @param session the session returned by {@link CameraDevice#createCaptureSession} 386 */ 387 public abstract void onConfigureFailed(CameraCaptureSession session); 388 389 /** 390 * This method is called every time the session has no more capture requests to process. 391 * 392 * <p>During the creation of a new session, this callback is invoked right after 393 * {@link #onConfigured} if no capture requests were submitted to the session prior to it 394 * completing configuration.</p> 395 * 396 * <p>Otherwise, this callback will be invoked any time the session finishes processing 397 * all of its active capture requests, and no repeating request or burst is set up.</p> 398 * 399 * @param session the session returned by {@link CameraDevice#createCaptureSession} 400 * 401 */ 402 public void onReady(CameraCaptureSession session) { 403 // default empty implementation 404 } 405 406 /** 407 * This method is called when the session starts actively processing capture requests. 408 * 409 * <p>If capture requests are submitted prior to {@link #onConfigured} being called, 410 * then the session will start processing those requests immediately after the callback, 411 * and this method will be immediately called after {@link #onConfigured}. 412 * 413 * <p>If the session runs out of capture requests to process and calls {@link #onReady}, 414 * then this callback will be invoked again once new requests are submitted for capture.</p> 415 * 416 * @param session the session returned by {@link CameraDevice#createCaptureSession} 417 */ 418 public void onActive(CameraCaptureSession session) { 419 // default empty implementation 420 } 421 422 /** 423 * This method is called when the session is closed. 424 * 425 * <p>A session is closed when a new session is created by the parent camera device, 426 * or when the parent camera device is closed (either by the user closing the device, 427 * or due to a camera device disconnection or fatal error).</p> 428 * 429 * <p>Once a session is closed, all methods on it will throw an IllegalStateException, and 430 * any repeating requests or bursts are stopped (as if {@link #stopRepeating()} was called). 431 * However, any in-progress capture requests submitted to the session will be completed 432 * as normal.</p> 433 * 434 * @param session the session returned by {@link CameraDevice#createCaptureSession} 435 */ 436 public void onClosed(CameraCaptureSession session) { 437 // default empty implementation 438 } 439 } 440 441 /** 442 * Temporary for migrating to Callback naming 443 * @hide 444 */ 445 public static abstract class StateListener extends StateCallback { 446 } 447 448 /** 449 * <p>A callback object for tracking the progress of a {@link CaptureRequest} submitted to the 450 * camera device.</p> 451 * 452 * <p>This callback is invoked when a request triggers a capture to start, 453 * and when the capture is complete. In case on an error capturing an image, 454 * the error method is triggered instead of the completion method.</p> 455 * 456 * @see #capture 457 * @see #captureBurst 458 * @see #setRepeatingRequest 459 * @see #setRepeatingBurst 460 */ 461 public static abstract class CaptureCallback { 462 463 /** 464 * This constant is used to indicate that no images were captured for 465 * the request. 466 * 467 * @hide 468 */ 469 public static final int NO_FRAMES_CAPTURED = -1; 470 471 /** 472 * This method is called when the camera device has started capturing 473 * the output image for the request, at the beginning of image exposure. 474 * 475 * <p>This callback is invoked right as the capture of a frame begins, 476 * so it is the most appropriate time for playing a shutter sound, 477 * or triggering UI indicators of capture.</p> 478 * 479 * <p>The request that is being used for this capture is provided, along 480 * with the actual timestamp for the start of exposure. This timestamp 481 * matches the timestamp that will be included in 482 * {@link CaptureResult#SENSOR_TIMESTAMP the result timestamp field}, 483 * and in the buffers sent to each output Surface. These buffer 484 * timestamps are accessible through, for example, 485 * {@link android.media.Image#getTimestamp() Image.getTimestamp()} or 486 * {@link android.graphics.SurfaceTexture#getTimestamp()}.</p> 487 * 488 * <p>For the simplest way to play a shutter sound camera shutter or a 489 * video recording start/stop sound, see the 490 * {@link android.media.MediaActionSound} class.</p> 491 * 492 * <p>The default implementation of this method does nothing.</p> 493 * 494 * @param session the session returned by {@link CameraDevice#createCaptureSession} 495 * @param request the request for the capture that just begun 496 * @param timestamp the timestamp at start of capture, in nanoseconds. 497 * 498 * @see android.media.MediaActionSound 499 */ 500 public void onCaptureStarted(CameraCaptureSession session, 501 CaptureRequest request, long timestamp) { 502 // default empty implementation 503 } 504 505 /** 506 * This method is called when some results from an image capture are 507 * available. 508 * 509 * <p>The result provided here will contain some subset of the fields of 510 * a full result. Multiple onCapturePartial calls may happen per 511 * capture; a given result field will only be present in one partial 512 * capture at most. The final onCaptureCompleted call will always 513 * contain all the fields, whether onCapturePartial was called or 514 * not.</p> 515 * 516 * <p>The default implementation of this method does nothing.</p> 517 * 518 * @param session the session returned by {@link CameraDevice#createCaptureSession} 519 * @param request The request that was given to the CameraDevice 520 * @param result The partial output metadata from the capture, which 521 * includes a subset of the CaptureResult fields. 522 * 523 * @see #capture 524 * @see #captureBurst 525 * @see #setRepeatingRequest 526 * @see #setRepeatingBurst 527 * 528 * @hide 529 */ 530 public void onCapturePartial(CameraCaptureSession session, 531 CaptureRequest request, CaptureResult result) { 532 // default empty implementation 533 } 534 535 /** 536 * This method is called when an image capture makes partial forward progress; some 537 * (but not all) results from an image capture are available. 538 * 539 * <p>The result provided here will contain some subset of the fields of 540 * a full result. Multiple {@link #onCaptureProgressed} calls may happen per 541 * capture; a given result field will only be present in one partial 542 * capture at most. The final {@link #onCaptureCompleted} call will always 543 * contain all the fields (in particular, the union of all the fields of all 544 * the partial results composing the total result).</p> 545 * 546 * <p>For each request, some result data might be available earlier than others. The typical 547 * delay between each partial result (per request) is a single frame interval. 548 * For performance-oriented use-cases, applications should query the metadata they need 549 * to make forward progress from the partial results and avoid waiting for the completed 550 * result.</p> 551 * 552 * <p>Each request will generate at least {@code 1} partial results, and at most 553 * {@link CameraCharacteristics#REQUEST_PARTIAL_RESULT_COUNT} partial results.</p> 554 * 555 * <p>Depending on the request settings, the number of partial results per request 556 * will vary, although typically the partial count could be the same as long as the 557 * camera device subsystems enabled stay the same.</p> 558 * 559 * <p>The default implementation of this method does nothing.</p> 560 * 561 * @param session the session returned by {@link CameraDevice#createCaptureSession} 562 * @param request The request that was given to the CameraDevice 563 * @param partialResult The partial output metadata from the capture, which 564 * includes a subset of the {@link TotalCaptureResult} fields. 565 * 566 * @see #capture 567 * @see #captureBurst 568 * @see #setRepeatingRequest 569 * @see #setRepeatingBurst 570 */ 571 public void onCaptureProgressed(CameraCaptureSession session, 572 CaptureRequest request, CaptureResult partialResult) { 573 // default empty implementation 574 } 575 576 /** 577 * This method is called when an image capture has fully completed and all the 578 * result metadata is available. 579 * 580 * <p>This callback will always fire after the last {@link #onCaptureProgressed}; 581 * in other words, no more partial results will be delivered once the completed result 582 * is available.</p> 583 * 584 * <p>For performance-intensive use-cases where latency is a factor, consider 585 * using {@link #onCaptureProgressed} instead.</p> 586 * 587 * <p>The default implementation of this method does nothing.</p> 588 * 589 * @param session the session returned by {@link CameraDevice#createCaptureSession} 590 * @param request The request that was given to the CameraDevice 591 * @param result The total output metadata from the capture, including the 592 * final capture parameters and the state of the camera system during 593 * capture. 594 * 595 * @see #capture 596 * @see #captureBurst 597 * @see #setRepeatingRequest 598 * @see #setRepeatingBurst 599 */ 600 public void onCaptureCompleted(CameraCaptureSession session, 601 CaptureRequest request, TotalCaptureResult result) { 602 // default empty implementation 603 } 604 605 /** 606 * This method is called instead of {@link #onCaptureCompleted} when the 607 * camera device failed to produce a {@link CaptureResult} for the 608 * request. 609 * 610 * <p>Other requests are unaffected, and some or all image buffers from 611 * the capture may have been pushed to their respective output 612 * streams.</p> 613 * 614 * <p>The default implementation of this method does nothing.</p> 615 * 616 * @param session 617 * The session returned by {@link CameraDevice#createCaptureSession} 618 * @param request 619 * The request that was given to the CameraDevice 620 * @param failure 621 * The output failure from the capture, including the failure reason 622 * and the frame number. 623 * 624 * @see #capture 625 * @see #captureBurst 626 * @see #setRepeatingRequest 627 * @see #setRepeatingBurst 628 */ 629 public void onCaptureFailed(CameraCaptureSession session, 630 CaptureRequest request, CaptureFailure failure) { 631 // default empty implementation 632 } 633 634 /** 635 * This method is called independently of the others in CaptureCallback, 636 * when a capture sequence finishes and all {@link CaptureResult} 637 * or {@link CaptureFailure} for it have been returned via this listener. 638 * 639 * <p>In total, there will be at least one result/failure returned by this listener 640 * before this callback is invoked. If the capture sequence is aborted before any 641 * requests have been processed, {@link #onCaptureSequenceAborted} is invoked instead.</p> 642 * 643 * <p>The default implementation does nothing.</p> 644 * 645 * @param session 646 * The session returned by {@link CameraDevice#createCaptureSession} 647 * @param sequenceId 648 * A sequence ID returned by the {@link #capture} family of functions. 649 * @param frameNumber 650 * The last frame number (returned by {@link CaptureResult#getFrameNumber} 651 * or {@link CaptureFailure#getFrameNumber}) in the capture sequence. 652 * 653 * @see CaptureResult#getFrameNumber() 654 * @see CaptureFailure#getFrameNumber() 655 * @see CaptureResult#getSequenceId() 656 * @see CaptureFailure#getSequenceId() 657 * @see #onCaptureSequenceAborted 658 */ 659 public void onCaptureSequenceCompleted(CameraCaptureSession session, 660 int sequenceId, long frameNumber) { 661 // default empty implementation 662 } 663 664 /** 665 * This method is called independently of the others in CaptureCallback, 666 * when a capture sequence aborts before any {@link CaptureResult} 667 * or {@link CaptureFailure} for it have been returned via this listener. 668 * 669 * <p>Due to the asynchronous nature of the camera device, not all submitted captures 670 * are immediately processed. It is possible to clear out the pending requests 671 * by a variety of operations such as {@link CameraCaptureSession#stopRepeating} or 672 * {@link CameraCaptureSession#abortCaptures}. When such an event happens, 673 * {@link #onCaptureSequenceCompleted} will not be called.</p> 674 * 675 * <p>The default implementation does nothing.</p> 676 * 677 * @param session 678 * The session returned by {@link CameraDevice#createCaptureSession} 679 * @param sequenceId 680 * A sequence ID returned by the {@link #capture} family of functions. 681 * 682 * @see CaptureResult#getFrameNumber() 683 * @see CaptureFailure#getFrameNumber() 684 * @see CaptureResult#getSequenceId() 685 * @see CaptureFailure#getSequenceId() 686 * @see #onCaptureSequenceCompleted 687 */ 688 public void onCaptureSequenceAborted(CameraCaptureSession session, 689 int sequenceId) { 690 // default empty implementation 691 } 692 } 693 694 /** 695 * Temporary for migrating to Callback naming 696 * @hide 697 */ 698 public static abstract class CaptureListener extends CaptureCallback { 699 } 700 701} 702