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