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