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