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