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