1 /* 2 * Copyright (C) 2013 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.os.Handler; 20 import android.view.Surface; 21 22 import java.util.List; 23 24 /** 25 * <p>The CameraDevice class is an interface to a single camera connected to an 26 * Android device, allowing for fine-grain control of image capture and 27 * post-processing at high frame rates.</p> 28 * 29 * <p>Your application must declare the 30 * {@link android.Manifest.permission#CAMERA Camera} permission in its manifest 31 * in order to access camera devices.</p> 32 * 33 * <p>A given camera device may provide support at one of two levels: limited or 34 * full. If a device only supports the limited level, then Camera2 exposes a 35 * feature set that is roughly equivalent to the older 36 * {@link android.hardware.Camera Camera} API, although with a cleaner and more 37 * efficient interface. Devices that implement the full level of support 38 * provide substantially improved capabilities over the older camera 39 * API. Applications that target the limited level devices will run unchanged on 40 * the full-level devices; if your application requires a full-level device for 41 * proper operation, declare the "android.hardware.camera2.full" feature in your 42 * manifest.</p> 43 * 44 * @see CameraManager#openCamera 45 * @see android.Manifest.permission#CAMERA 46 */ 47 public interface CameraDevice extends AutoCloseable { 48 49 /** 50 * Create a request suitable for a camera preview window. Specifically, this 51 * means that high frame rate is given priority over the highest-quality 52 * post-processing. These requests would normally be used with the 53 * {@link #setRepeatingRequest} method. 54 * 55 * @see #createCaptureRequest 56 */ 57 public static final int TEMPLATE_PREVIEW = 1; 58 59 /** 60 * Create a request suitable for still image capture. Specifically, this 61 * means prioritizing image quality over frame rate. These requests would 62 * commonly be used with the {@link #capture} method. 63 * 64 * @see #createCaptureRequest 65 */ 66 public static final int TEMPLATE_STILL_CAPTURE = 2; 67 68 /** 69 * Create a request suitable for video recording. Specifically, this means 70 * that a stable frame rate is used, and post-processing is set for 71 * recording quality. These requests would commonly be used with the 72 * {@link #setRepeatingRequest} method. 73 * 74 * @see #createCaptureRequest 75 */ 76 public static final int TEMPLATE_RECORD = 3; 77 78 /** 79 * Create a request suitable for still image capture while recording 80 * video. Specifically, this means maximizing image quality without 81 * disrupting the ongoing recording. These requests would commonly be used 82 * with the {@link #capture} method while a request based on 83 * {@link #TEMPLATE_RECORD} is is in use with {@link #setRepeatingRequest}. 84 * 85 * @see #createCaptureRequest 86 */ 87 public static final int TEMPLATE_VIDEO_SNAPSHOT = 4; 88 89 /** 90 * Create a request suitable for zero shutter lag still capture. This means 91 * means maximizing image quality without compromising preview frame rate. 92 * AE/AWB/AF should be on auto mode. 93 * 94 * @see #createCaptureRequest 95 * @hide 96 */ 97 public static final int TEMPLATE_ZERO_SHUTTER_LAG = 5; 98 99 /** 100 * A basic template for direct application control of capture 101 * parameters. All automatic control is disabled (auto-exposure, auto-white 102 * balance, auto-focus), and post-processing parameters are set to preview 103 * quality. The manual capture parameters (exposure, sensitivity, and so on) 104 * are set to reasonable defaults, but should be overriden by the 105 * application depending on the intended use case. 106 * 107 * @see #createCaptureRequest 108 * @hide 109 */ 110 public static final int TEMPLATE_MANUAL = 6; 111 112 /** 113 * Get the ID of this camera device. 114 * 115 * <p>This matches the ID given to {@link CameraManager#openCamera} to instantiate this 116 * this camera device.</p> 117 * 118 * <p>This ID can be used to query the camera device's {@link 119 * CameraCharacteristics fixed properties} with {@link 120 * CameraManager#getCameraCharacteristics}.</p> 121 * 122 * <p>This method can be called even if the device has been closed or has encountered 123 * a serious error.</p> 124 * 125 * @return the ID for this camera device 126 * 127 * @see CameraManager#getCameraCharacteristics 128 * @see CameraManager#getCameraIdList 129 */ 130 public String getId(); 131 132 /** 133 * <p>Set up a new output set of Surfaces for the camera device.</p> 134 * 135 * <p>The configuration determines the set of potential output Surfaces for 136 * the camera device for each capture request. A given request may use all 137 * or a only some of the outputs. This method must be called before requests 138 * can be submitted to the camera with {@link #capture capture}, 139 * {@link #captureBurst captureBurst}, 140 * {@link #setRepeatingRequest setRepeatingRequest}, or 141 * {@link #setRepeatingBurst setRepeatingBurst}.</p> 142 * 143 * <p>Surfaces suitable for inclusion as a camera output can be created for 144 * various use cases and targets:</p> 145 * 146 * <ul> 147 * 148 * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Set 149 * the size of the Surface with 150 * {@link android.view.SurfaceHolder#setFixedSize} to be one of the 151 * supported 152 * {@link CameraCharacteristics#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 153 * before calling {@link android.view.SurfaceHolder#getSurface}.</li> 154 * 155 * <li>For accessing through an OpenGL texture via a 156 * {@link android.graphics.SurfaceTexture SurfaceTexture}: Set the size of 157 * the SurfaceTexture with 158 * {@link android.graphics.SurfaceTexture#setDefaultBufferSize} to be one 159 * of the supported 160 * {@link CameraCharacteristics#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 161 * before creating a Surface from the SurfaceTexture with 162 * {@link Surface#Surface}.</li> 163 * 164 * <li>For recording with {@link android.media.MediaCodec}: Call 165 * {@link android.media.MediaCodec#createInputSurface} after configuring 166 * the media codec to use one of the 167 * {@link CameraCharacteristics#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 168 * </li> 169 * 170 * <li>For recording with {@link android.media.MediaRecorder}: TODO</li> 171 * 172 * <li>For efficient YUV processing with {@link android.renderscript}: 173 * Create a RenderScript 174 * {@link android.renderscript.Allocation Allocation} with a supported YUV 175 * type, the IO_INPUT flag, and one of the supported 176 * {@link CameraCharacteristics#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes}. Then 177 * obtain the Surface with 178 * {@link android.renderscript.Allocation#getSurface}.</li> 179 * 180 * <li>For access to uncompressed or JPEG data in the application: Create a 181 * {@link android.media.ImageReader} object with the desired 182 * {@link CameraCharacteristics#SCALER_AVAILABLE_FORMATS image format}, and a 183 * size from the matching 184 * {@link CameraCharacteristics#SCALER_AVAILABLE_PROCESSED_SIZES processed}, 185 * {@link CameraCharacteristics#SCALER_AVAILABLE_JPEG_SIZES jpeg}. Then obtain 186 * a Surface from it.</li> 187 * 188 * </ul> 189 * 190 * </p> 191 * 192 * <p>This function can take several hundred milliseconds to execute, since 193 * camera hardware may need to be powered on or reconfigured.</p> 194 * 195 * <p>The camera device will query each Surface's size and formats upon this 196 * call, so they must be set to a valid setting at this time (in particular: 197 * if the format is user-visible, it must be one of android.scaler.availableFormats; 198 * and the size must be one of android.scaler.available[Processed|Jpeg]Sizes).</p> 199 * 200 * <p>When this method is called with valid Surfaces, the device will transition to the {@link 201 * StateListener#onBusy busy state}. Once configuration is complete, the device will transition 202 * into the {@link StateListener#onIdle idle state}. Capture requests using the newly-configured 203 * Surfaces may then be submitted with {@link #capture}, {@link #captureBurst}, {@link 204 * #setRepeatingRequest}, or {@link #setRepeatingBurst}.</p> 205 * 206 * <p>If this method is called while the camera device is still actively processing previously 207 * submitted captures, then the following sequence of events occurs: The device transitions to 208 * the busy state and calls the {@link StateListener#onBusy} callback. Second, if a repeating 209 * request is set it is cleared. Third, the device finishes up all in-flight and pending 210 * requests. Finally, once the device is idle, it then reconfigures its outputs, and calls the 211 * {@link StateListener#onIdle} method once it is again ready to accept capture 212 * requests. Therefore, no submitted work is discarded. To idle as fast as possible, use {@link 213 * #flush} and wait for the idle callback before calling configureOutputs. This will discard 214 * work, but reaches the new configuration sooner.</p> 215 * 216 * <p>Using larger resolution outputs, or more outputs, can result in slower 217 * output rate from the device.</p> 218 * 219 * <p>Configuring the outputs with an empty or null list will transition the camera into an 220 * {@link StateListener#onUnconfigured unconfigured state} instead of the {@link 221 * StateListener#onIdle idle state}. </p> 222 * 223 * <p>Calling configureOutputs with the same arguments as the last call to 224 * configureOutputs has no effect, and the {@link StateListener#onBusy busy} 225 * and {@link StateListener#onIdle idle} state transitions will happen 226 * immediately.</p> 227 * 228 * @param outputs The new set of Surfaces that should be made available as 229 * targets for captured image data. 230 * 231 * @throws IllegalArgumentException if the set of output Surfaces do not 232 * meet the requirements 233 * @throws CameraAccessException if the camera device is no longer connected or has 234 * encountered a fatal error 235 * @throws IllegalStateException if the camera device is not idle, or 236 * if the camera device has been closed 237 * 238 * @see StateListener#onBusy 239 * @see StateListener#onIdle 240 * @see StateListener#onActive 241 * @see StateListener#onUnconfigured 242 * @see #stopRepeating 243 * @see #flush 244 */ 245 public void configureOutputs(List<Surface> outputs) throws CameraAccessException; 246 247 /** 248 * <p>Create a {@link CaptureRequest.Builder} for new capture requests, 249 * initialized with template for a target use case. The settings are chosen 250 * to be the best options for the specific camera device, so it is not 251 * recommended to reuse the same request for a different camera device; 252 * create a builder specific for that device and template and override the 253 * settings as desired, instead.</p> 254 * 255 * @param templateType An enumeration selecting the use case for this 256 * request; one of the CameraDevice.TEMPLATE_ values. 257 * @return a builder for a capture request, initialized with default 258 * settings for that template, and no output streams 259 * 260 * @throws IllegalArgumentException if the templateType is not in the list 261 * of supported templates. 262 * @throws CameraAccessException if the camera device is no longer connected or has 263 * encountered a fatal error 264 * @throws IllegalStateException if the camera device has been closed 265 * 266 * @see #TEMPLATE_PREVIEW 267 * @see #TEMPLATE_RECORD 268 * @see #TEMPLATE_STILL_CAPTURE 269 * @see #TEMPLATE_VIDEO_SNAPSHOT 270 * @see #TEMPLATE_MANUAL 271 */ 272 public CaptureRequest.Builder createCaptureRequest(int templateType) 273 throws CameraAccessException; 274 275 /** 276 * <p>Submit a request for an image to be captured by this CameraDevice.</p> 277 * 278 * <p>The request defines all the parameters for capturing the single image, 279 * including sensor, lens, flash, and post-processing settings.</p> 280 * 281 * <p>Each request will produce one {@link CaptureResult} and produce new 282 * frames for one or more target Surfaces, set with the CaptureRequest 283 * builder's {@link CaptureRequest.Builder#addTarget} method. The target 284 * surfaces must be configured as active outputs with 285 * {@link #configureOutputs} before calling this method.</p> 286 * 287 * <p>Multiple requests can be in progress at once. They are processed in 288 * first-in, first-out order, with minimal delays between each 289 * capture. Requests submitted through this method have higher priority than 290 * those submitted through {@link #setRepeatingRequest} or 291 * {@link #setRepeatingBurst}, and will be processed as soon as the current 292 * repeat/repeatBurst processing completes.</p> 293 * 294 * @param request the settings for this capture 295 * @param listener The callback object to notify once this request has been 296 * processed. If null, no metadata will be produced for this capture, 297 * although image data will still be produced. 298 * @param handler the handler on which the listener should be invoked, or 299 * {@code null} to use the current thread's {@link android.os.Looper 300 * looper}. 301 * 302 * @return int A unique capture sequence ID used by 303 * {@link CaptureListener#onCaptureSequenceCompleted}. 304 * 305 * @throws CameraAccessException if the camera device is no longer connected or has 306 * encountered a fatal error 307 * @throws IllegalStateException if the camera is currently busy or unconfigured, 308 * or the camera device has been closed. 309 * @throws IllegalArgumentException If the request targets Surfaces not 310 * currently configured as outputs. Or if the handler is null, the listener 311 * is not null, and the calling thread has no looper. 312 * 313 * @see #captureBurst 314 * @see #setRepeatingRequest 315 * @see #setRepeatingBurst 316 */ 317 public int capture(CaptureRequest request, CaptureListener listener, Handler handler) 318 throws CameraAccessException; 319 320 /** 321 * Submit a list of requests to be captured in sequence as a burst. The 322 * burst will be captured in the minimum amount of time possible, and will 323 * not be interleaved with requests submitted by other capture or repeat 324 * calls. 325 * 326 * <p>The requests will be captured in order, each capture producing one 327 * {@link CaptureResult} and image buffers for one or more target 328 * {@link android.view.Surface surfaces}. The target surfaces for each 329 * request (set with {@link CaptureRequest.Builder#addTarget}) must be 330 * configured as active outputs with {@link #configureOutputs} before 331 * calling this method.</p> 332 * 333 * <p>The main difference between this method and simply calling 334 * {@link #capture} repeatedly is that this method guarantees that no 335 * other requests will be interspersed with the burst.</p> 336 * 337 * @param requests the list of settings for this burst capture 338 * @param listener The callback object to notify each time one of the 339 * requests in the burst has been processed. If null, no metadata will be 340 * produced for any requests in this burst, although image data will still 341 * be produced. 342 * @param handler the handler on which the listener should be invoked, or 343 * {@code null} to use the current thread's {@link android.os.Looper 344 * looper}. 345 * 346 * @return int A unique capture sequence ID used by 347 * {@link CaptureListener#onCaptureSequenceCompleted}. 348 * 349 * @throws CameraAccessException if the camera device is no longer connected or has 350 * encountered a fatal error 351 * @throws IllegalStateException if the camera is currently busy or unconfigured, 352 * or the camera device has been closed. 353 * @throws IllegalArgumentException If the requests target Surfaces not 354 * currently configured as outputs. Or if the handler is null, the listener 355 * is not null, and the calling thread has no looper. 356 * 357 * @see #capture 358 * @see #setRepeatingRequest 359 * @see #setRepeatingBurst 360 */ 361 public int captureBurst(List<CaptureRequest> requests, CaptureListener listener, 362 Handler handler) throws CameraAccessException; 363 364 /** 365 * Request endlessly repeating capture of images by this CameraDevice. 366 * 367 * <p>With this method, the CameraDevice will continually capture images 368 * using the settings in the provided {@link CaptureRequest}, at the maximum 369 * rate possible.</p> 370 * 371 * <p>Repeating requests are a simple way for an application to maintain a 372 * preview or other continuous stream of frames, without having to 373 * continually submit identical requests through {@link #capture}.</p> 374 * 375 * <p>Repeat requests have lower priority than those submitted 376 * through {@link #capture} or {@link #captureBurst}, so if 377 * {@link #capture} is called when a repeating request is active, the 378 * capture request will be processed before any further repeating 379 * requests are processed.<p> 380 * 381 * <p>Repeating requests are a simple way for an application to maintain a 382 * preview or other continuous stream of frames, without having to submit 383 * requests through {@link #capture} at video rates.</p> 384 * 385 * <p>To stop the repeating capture, call {@link #stopRepeating}. Calling 386 * {@link #flush} will also clear the request.</p> 387 * 388 * <p>Calling this method will replace any earlier repeating request or 389 * burst set up by this method or {@link #setRepeatingBurst}, although any 390 * in-progress burst will be completed before the new repeat request will be 391 * used.</p> 392 * 393 * @param request the request to repeat indefinitely 394 * @param listener The callback object to notify every time the 395 * request finishes processing. If null, no metadata will be 396 * produced for this stream of requests, although image data will 397 * still be produced. 398 * @param handler the handler on which the listener should be invoked, or 399 * {@code null} to use the current thread's {@link android.os.Looper 400 * looper}. 401 * 402 * @return int A unique capture sequence ID used by 403 * {@link CaptureListener#onCaptureSequenceCompleted}. 404 * 405 * @throws CameraAccessException if the camera device is no longer connected or has 406 * encountered a fatal error 407 * @throws IllegalStateException if the camera is currently busy or unconfigured, 408 * or the camera device has been closed. 409 * @throws IllegalArgumentException If the requests reference Surfaces not 410 * currently configured as outputs. Or if the handler is null, the listener 411 * is not null, and the calling thread has no looper. 412 * 413 * @see #capture 414 * @see #captureBurst 415 * @see #setRepeatingBurst 416 * @see #stopRepeating 417 * @see #flush 418 */ 419 public int setRepeatingRequest(CaptureRequest request, CaptureListener listener, 420 Handler handler) throws CameraAccessException; 421 422 /** 423 * <p>Request endlessly repeating capture of a sequence of images by this 424 * CameraDevice.</p> 425 * 426 * <p>With this method, the CameraDevice will continually capture images, 427 * cycling through the settings in the provided list of 428 * {@link CaptureRequest CaptureRequests}, at the maximum rate possible.</p> 429 * 430 * <p>If a request is submitted through {@link #capture} or 431 * {@link #captureBurst}, the current repetition of the request list will be 432 * completed before the higher-priority request is handled. This guarantees 433 * that the application always receives a complete repeat burst captured in 434 * minimal time, instead of bursts interleaved with higher-priority 435 * captures, or incomplete captures.</p> 436 * 437 * <p>Repeating burst requests are a simple way for an application to 438 * maintain a preview or other continuous stream of frames where each 439 * request is different in a predicatable way, without having to continually 440 * submit requests through {@link #captureBurst} .</p> 441 * 442 * <p>To stop the repeating capture, call {@link #stopRepeating}. Any 443 * ongoing burst will still be completed, however. Calling 444 * {@link #flush} will also clear the request.</p> 445 * 446 * <p>Calling this method will replace a previously-set repeating request or 447 * burst set up by this method or {@link #setRepeatingRequest}, although any 448 * in-progress burst will be completed before the new repeat burst will be 449 * used.</p> 450 * 451 * @param requests the list of requests to cycle through indefinitely 452 * @param listener The callback object to notify each time one of the 453 * requests in the repeating bursts has finished processing. If null, no 454 * metadata will be produced for this stream of requests, although image 455 * data will 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 CaptureListener#onCaptureSequenceCompleted}. 462 * 463 * @throws CameraAccessException if the camera device is no longer connected or has 464 * encountered a fatal error 465 * @throws IllegalStateException if the camera is currently busy or unconfigured, 466 * or the camera device has been closed. 467 * @throws IllegalArgumentException If the requests reference Surfaces not 468 * currently configured as outputs. Or if the handler is null, the listener 469 * is not null, and the calling thread has no looper. 470 * 471 * @see #capture 472 * @see #captureBurst 473 * @see #setRepeatingRequest 474 * @see #stopRepeating 475 * @see #flush 476 */ 477 public int setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener, 478 Handler handler) throws CameraAccessException; 479 480 /** 481 * <p>Cancel any ongoing repeating capture set by either 482 * {@link #setRepeatingRequest setRepeatingRequest} or 483 * {@link #setRepeatingBurst}. Has no effect on requests submitted through 484 * {@link #capture capture} or {@link #captureBurst captureBurst}.</p> 485 * 486 * <p>Any currently in-flight captures will still complete, as will any 487 * burst that is mid-capture. To ensure that the device has finished 488 * processing all of its capture requests and is in idle state, wait for the 489 * {@link StateListener#onIdle} callback after calling this 490 * method..</p> 491 * 492 * @throws CameraAccessException if the camera device is no longer connected or has 493 * encountered a fatal error 494 * @throws IllegalStateException if the camera is currently busy or unconfigured, 495 * or the camera device has been closed. 496 * 497 * @see #setRepeatingRequest 498 * @see #setRepeatingBurst 499 * @see StateListener#onIdle 500 */ 501 public void stopRepeating() throws CameraAccessException; 502 503 /** 504 * <p>Wait until all the submitted requests have finished processing</p> 505 * 506 * <p>This method blocks until all the requests that have been submitted to 507 * the camera device, either through {@link #capture capture}, 508 * {@link #captureBurst captureBurst}, 509 * {@link #setRepeatingRequest setRepeatingRequest}, or 510 * {@link #setRepeatingBurst setRepeatingBurst}, have completed their 511 * processing.</p> 512 * 513 * <p>Once this call returns successfully, the device is in an idle state, 514 * and can be reconfigured with {@link #configureOutputs configureOutputs}.</p> 515 * 516 * <p>This method cannot be used if there is an active repeating request or 517 * burst, set with {@link #setRepeatingRequest setRepeatingRequest} or 518 * {@link #setRepeatingBurst setRepeatingBurst}. Call 519 * {@link #stopRepeating stopRepeating} before calling this method.</p> 520 * 521 * @throws CameraAccessException if the camera device is no longer connected 522 * @throws IllegalStateException if the camera device has been closed, the 523 * device has encountered a fatal error, or if there is an active repeating 524 * request or burst. 525 */ 526 public void waitUntilIdle() throws CameraAccessException; 527 528 /** 529 * Flush all captures currently pending and in-progress as fast as 530 * possible. 531 * 532 * <p>The camera device will discard all of its current work as fast as 533 * possible. Some in-flight captures may complete successfully and call 534 * {@link CaptureListener#onCaptureCompleted}, while others will trigger 535 * their {@link CaptureListener#onCaptureFailed} callbacks. If a repeating 536 * request or a repeating burst is set, it will be cleared by the flush.</p> 537 * 538 * <p>This method is the fastest way to idle the camera device for 539 * reconfiguration with {@link #configureOutputs}, at the cost of discarding 540 * in-progress work. Once the flush is complete, the idle callback will be 541 * called.</p> 542 * 543 * <p>Flushing will introduce at least a brief pause in the stream of data 544 * from the camera device, since once the flush is complete, the first new 545 * request has to make it through the entire camera pipeline before new 546 * output buffers are produced.</p> 547 * 548 * <p>This means that using {@code flush()} to simply remove pending 549 * requests is not recommended; it's best used for quickly switching output 550 * configurations, or for cancelling long in-progress requests (such as a 551 * multi-second capture).</p> 552 * 553 * @throws CameraAccessException if the camera device is no longer connected or has 554 * encountered a fatal error 555 * @throws IllegalStateException if the camera is not idle/active, 556 * or the camera device has been closed. 557 * 558 * @see #setRepeatingRequest 559 * @see #setRepeatingBurst 560 * @see #configureOutputs 561 */ 562 public void flush() throws CameraAccessException; 563 564 /** 565 * Close the connection to this camera device. 566 * 567 * <p>After this call, all calls to 568 * the camera device interface will throw a {@link IllegalStateException}, 569 * except for calls to close(). Once the device has fully shut down, the 570 * {@link StateListener#onClosed} callback will be called, and the camera is 571 * free to be re-opened.</p> 572 * 573 * <p>After this call, besides the final {@link StateListener#onClosed} call, no calls to the 574 * device's {@link StateListener} will occur, and any remaining submitted capture requests will 575 * not fire their {@link CaptureListener} callbacks.</p> 576 * 577 * <p>To shut down as fast as possible, call the {@link #flush} method and then {@link #close} 578 * once the flush completes. This will discard some capture requests, but results in faster 579 * shutdown.</p> 580 */ 581 @Override 582 public void close(); 583 584 /** 585 * <p>A listener for tracking the progress of a {@link CaptureRequest} 586 * submitted to the camera device.</p> 587 * 588 * <p>This listener is called when a request triggers a capture to start, 589 * and when the capture is complete. In case on an error capturing an image, 590 * the error method is triggered instead of the completion method.</p> 591 * 592 * @see #capture 593 * @see #captureBurst 594 * @see #setRepeatingRequest 595 * @see #setRepeatingBurst 596 */ 597 public static abstract class CaptureListener { 598 599 /** 600 * This method is called when the camera device has started capturing 601 * the output image for the request, at the beginning of image exposure. 602 * 603 * <p>This callback is invoked right as the capture of a frame begins, 604 * so it is the most appropriate time for playing a shutter sound, 605 * or triggering UI indicators of capture.</p> 606 * 607 * <p>The request that is being used for this capture is provided, along 608 * with the actual timestamp for the start of exposure. This timestamp 609 * matches the timestamp that will be included in 610 * {@link CaptureResult#SENSOR_TIMESTAMP the result timestamp field}, 611 * and in the buffers sent to each output Surface. These buffer 612 * timestamps are accessible through, for example, 613 * {@link android.media.Image#getTimestamp() Image.getTimestamp()} or 614 * {@link android.graphics.SurfaceTexture#getTimestamp()}.</p> 615 * 616 * <p>For the simplest way to play a shutter sound camera shutter or a 617 * video recording start/stop sound, see the 618 * {@link android.media.MediaActionSound} class.</p> 619 * 620 * <p>The default implementation of this method does nothing.</p> 621 * 622 * @param camera the CameraDevice sending the callback 623 * @param request the request for the capture that just begun 624 * @param timestamp the timestamp at start of capture, in nanoseconds. 625 * 626 * @see android.media.MediaActionSound 627 */ 628 public void onCaptureStarted(CameraDevice camera, 629 CaptureRequest request, long timestamp) { 630 // default empty implementation 631 } 632 633 /** 634 * This method is called when some results from an image capture are 635 * available. 636 * 637 * <p>The result provided here will contain some subset of the fields of 638 * a full result. Multiple onCapturePartial calls may happen per 639 * capture; a given result field will only be present in one partial 640 * capture at most. The final onCaptureCompleted call will always 641 * contain all the fields, whether onCapturePartial was called or 642 * not.</p> 643 * 644 * <p>The default implementation of this method does nothing.</p> 645 * 646 * @param camera The CameraDevice sending the callback. 647 * @param request The request that was given to the CameraDevice 648 * @param result The partial output metadata from the capture, which 649 * includes a subset of the CaptureResult fields. 650 * 651 * @see #capture 652 * @see #captureBurst 653 * @see #setRepeatingRequest 654 * @see #setRepeatingBurst 655 * 656 * @hide 657 */ 658 public void onCapturePartial(CameraDevice camera, 659 CaptureRequest request, CaptureResult result) { 660 // default empty implementation 661 } 662 663 /** 664 * This method is called when an image capture has completed and the 665 * result metadata is available. 666 * 667 * <p>The default implementation of this method does nothing.</p> 668 * 669 * @param camera The CameraDevice sending the callback. 670 * @param request The request that was given to the CameraDevice 671 * @param result The output metadata from the capture, including the 672 * final capture parameters and the state of the camera system during 673 * capture. 674 * 675 * @see #capture 676 * @see #captureBurst 677 * @see #setRepeatingRequest 678 * @see #setRepeatingBurst 679 */ 680 public void onCaptureCompleted(CameraDevice camera, 681 CaptureRequest request, CaptureResult result) { 682 // default empty implementation 683 } 684 685 /** 686 * This method is called instead of {@link #onCaptureCompleted} when the 687 * camera device failed to produce a {@link CaptureResult} for the 688 * request. 689 * 690 * <p>Other requests are unaffected, and some or all image buffers from 691 * the capture may have been pushed to their respective output 692 * streams.</p> 693 * 694 * <p>The default implementation of this method does nothing.</p> 695 * 696 * @param camera 697 * The CameraDevice sending the callback. 698 * @param request 699 * The request that was given to the CameraDevice 700 * @param failure 701 * The output failure from the capture, including the failure reason 702 * and the frame number. 703 * 704 * @see #capture 705 * @see #captureBurst 706 * @see #setRepeatingRequest 707 * @see #setRepeatingBurst 708 */ 709 public void onCaptureFailed(CameraDevice camera, 710 CaptureRequest request, CaptureFailure failure) { 711 // default empty implementation 712 } 713 714 /** 715 * This method is called independently of the others in CaptureListener, 716 * when a capture sequence finishes and all {@link CaptureResult} 717 * or {@link CaptureFailure} for it have been returned via this listener. 718 * 719 * @param camera 720 * The CameraDevice sending the callback. 721 * @param sequenceId 722 * A sequence ID returned by the {@link #capture} family of functions. 723 * @param frameNumber 724 * The last frame number (returned by {@link CaptureResult#getFrameNumber} 725 * or {@link CaptureFailure#getFrameNumber}) in the capture sequence. 726 * 727 * @see CaptureResult#getFrameNumber() 728 * @see CaptureFailure#getFrameNumber() 729 * @see CaptureResult#getSequenceId() 730 * @see CaptureFailure#getSequenceId() 731 */ 732 public void onCaptureSequenceCompleted(CameraDevice camera, 733 int sequenceId, int frameNumber) { 734 // default empty implementation 735 } 736 } 737 738 /** 739 * A listener for notifications about the state of a camera 740 * device. 741 * 742 * <p>A listener must be provided to the {@link CameraManager#openCamera} 743 * method to open a camera device.</p> 744 * 745 * <p>These events include notifications about the device becoming idle ( 746 * allowing for {@link #configureOutputs} to be called), about device 747 * disconnection, and about unexpected device errors.</p> 748 * 749 * <p>Events about the progress of specific {@link CaptureRequest 750 * CaptureRequests} are provided through a {@link CaptureListener} given to 751 * the {@link #capture}, {@link #captureBurst}, {@link 752 * #setRepeatingRequest}, or {@link #setRepeatingBurst} methods. 753 * 754 * @see CameraManager#openCamera 755 */ 756 public static abstract class StateListener { 757 /** 758 * An error code that can be reported by {@link #onError} 759 * indicating that the camera device is in use already. 760 * 761 * <p> 762 * This error can be produced when opening the camera fails. 763 * </p> 764 * 765 * @see #onError 766 */ 767 public static final int ERROR_CAMERA_IN_USE = 1; 768 769 /** 770 * An error code that can be reported by {@link #onError} 771 * indicating that the camera device could not be opened 772 * because there are too many other open camera devices. 773 * 774 * <p> 775 * The system-wide limit for number of open cameras has been reached, 776 * and more camera devices cannot be opened until previous instances are 777 * closed. 778 * </p> 779 * 780 * <p> 781 * This error can be produced when opening the camera fails. 782 * </p> 783 * 784 * @see #onError 785 */ 786 public static final int ERROR_MAX_CAMERAS_IN_USE = 2; 787 788 /** 789 * An error code that can be reported by {@link #onError} 790 * indicating that the camera device could not be opened due to a device 791 * policy. 792 * 793 * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) 794 * @see #onError 795 */ 796 public static final int ERROR_CAMERA_DISABLED = 3; 797 798 /** 799 * An error code that can be reported by {@link #onError} 800 * indicating that the camera device has encountered a fatal error. 801 * 802 * <p>The camera device needs to be re-opened to be used again.</p> 803 * 804 * @see #onError 805 */ 806 public static final int ERROR_CAMERA_DEVICE = 4; 807 808 /** 809 * An error code that can be reported by {@link #onError} 810 * indicating that the camera service has encountered a fatal error. 811 * 812 * <p>The Android device may need to be shut down and restarted to restore 813 * camera function, or there may be a persistent hardware problem.</p> 814 * 815 * <p>An attempt at recovery <i>may</i> be possible by closing the 816 * CameraDevice and the CameraManager, and trying to acquire all resources 817 * again from scratch.</p> 818 * 819 * @see #onError 820 */ 821 public static final int ERROR_CAMERA_SERVICE = 5; 822 823 /** 824 * The method called when a camera device has finished opening. 825 * 826 * <p>An opened camera will immediately afterwards transition into 827 * {@link #onUnconfigured}.</p> 828 * 829 * @param camera the camera device that has become opened 830 */ 831 public abstract void onOpened(CameraDevice camera); // Must implement 832 833 /** 834 * The method called when a camera device has no outputs configured. 835 * 836 * <p>An unconfigured camera device needs to be configured with 837 * {@link CameraDevice#configureOutputs} before being able to 838 * submit any capture request.</p> 839 * 840 * <p>This state may be entered by a newly opened camera or by 841 * calling {@link CameraDevice#configureOutputs} with a null/empty 842 * list of Surfaces when idle.</p> 843 * 844 * <p>Any attempts to submit a capture request while in this state 845 * will result in an {@link IllegalStateException} being thrown.</p> 846 * 847 * <p>The default implementation of this method does nothing.</p> 848 * 849 * @param camera the camera device has that become unconfigured 850 */ 851 public void onUnconfigured(CameraDevice camera) { 852 // Default empty implementation 853 } 854 855 /** 856 * The method called when a camera device begins processing 857 * {@link CaptureRequest capture requests}. 858 * 859 * <p>A camera may not be re-configured while in this state. The camera 860 * will transition to the idle state once all pending captures have 861 * completed. If a repeating request is set, the camera will remain active 862 * until it is cleared and the remaining requests finish processing. To 863 * transition to the idle state as quickly as possible, call {@link #flush()}, 864 * which will idle the camera device as quickly as possible, likely canceling 865 * most in-progress captures.</p> 866 * 867 * <p>All calls except for {@link CameraDevice#configureOutputs} are 868 * legal while in this state. 869 * </p> 870 * 871 * <p>The default implementation of this method does nothing.</p> 872 * 873 * @param camera the camera device that has become active 874 * 875 * @see CameraDevice#capture 876 * @see CameraDevice#captureBurst 877 * @see CameraDevice#setRepeatingBurst 878 * @see CameraDevice#setRepeatingRequest 879 */ 880 public void onActive(CameraDevice camera) { 881 // Default empty implementation 882 } 883 884 /** 885 * The method called when a camera device is busy. 886 * 887 * <p>A camera becomes busy while it's outputs are being configured 888 * (after a call to {@link CameraDevice#configureOutputs} or while it's 889 * being flushed (after a call to {@link CameraDevice#flush}.</p> 890 * 891 * <p>Once the on-going operations are complete, the camera will automatically 892 * transition into {@link #onIdle} if there is at least one configured output, 893 * or {@link #onUnconfigured} otherwise.</p> 894 * 895 * <p>Any attempts to manipulate the camera while its is busy 896 * will result in an {@link IllegalStateException} being thrown.</p> 897 * 898 * <p>Only the following methods are valid to call while in this state: 899 * <ul> 900 * <li>{@link CameraDevice#getId}</li> 901 * <li>{@link CameraDevice#createCaptureRequest}</li> 902 * <li>{@link CameraDevice#close}</li> 903 * </ul> 904 * </p> 905 * 906 * <p>The default implementation of this method does nothing.</p> 907 * 908 * @param camera the camera device that has become busy 909 * 910 * @see CameraDevice#configureOutputs 911 * @see CameraDevice#flush 912 */ 913 public void onBusy(CameraDevice camera) { 914 // Default empty implementation 915 } 916 917 /** 918 * The method called when a camera device has been closed with 919 * {@link CameraDevice#close}. 920 * 921 * <p>Any attempt to call methods on this CameraDevice in the 922 * future will throw a {@link IllegalStateException}.</p> 923 * 924 * <p>The default implementation of this method does nothing.</p> 925 * 926 * @param camera the camera device that has become closed 927 */ 928 public void onClosed(CameraDevice camera) { 929 // Default empty implementation 930 } 931 932 /** 933 * The method called when a camera device has finished processing all 934 * submitted capture requests and has reached an idle state. 935 * 936 * <p>An idle camera device can have its outputs changed by calling {@link 937 * CameraDevice#configureOutputs}, which will transition it into the busy state.</p> 938 * 939 * <p>To idle and reconfigure outputs without canceling any submitted 940 * capture requests, the application needs to clear its repeating 941 * request/burst, if set, with {@link CameraDevice#stopRepeating}, and 942 * then wait for this callback to be called before calling {@link 943 * CameraDevice#configureOutputs}.</p> 944 * 945 * <p>To idle and reconfigure a camera device as fast as possible, the 946 * {@link CameraDevice#flush} method can be used, which will discard all 947 * pending and in-progress capture requests. Once the {@link 948 * CameraDevice#flush} method is called, the application must wait for 949 * this callback to fire before calling {@link 950 * CameraDevice#configureOutputs}.</p> 951 * 952 * <p>The default implementation of this method does nothing.</p> 953 * 954 * @param camera the camera device that has become idle 955 * 956 * @see CameraDevice#configureOutputs 957 * @see CameraDevice#stopRepeating 958 * @see CameraDevice#flush 959 */ 960 public void onIdle(CameraDevice camera) { 961 // Default empty implementation 962 } 963 964 /** 965 * The method called when a camera device is no longer available for 966 * use. 967 * 968 * <p>This callback may be called instead of {@link #onOpened} 969 * if opening the camera fails.</p> 970 * 971 * <p>Any attempt to call methods on this CameraDevice will throw a 972 * {@link CameraAccessException}. The disconnection could be due to a 973 * change in security policy or permissions; the physical disconnection 974 * of a removable camera device; or the camera being needed for a 975 * higher-priority use case.</p> 976 * 977 * <p>There may still be capture listener callbacks that are called 978 * after this method is called, or new image buffers that are delivered 979 * to active outputs.</p> 980 * 981 * <p>The default implementation logs a notice to the system log 982 * about the disconnection.</p> 983 * 984 * <p>You should clean up the camera with {@link CameraDevice#close} after 985 * this happens, as it is not recoverable until opening the camera again 986 * after it becomes {@link CameraManager.AvailabilityListener#onCameraAvailable available}. 987 * </p> 988 * 989 * @param camera the device that has been disconnected 990 */ 991 public abstract void onDisconnected(CameraDevice camera); // Must implement 992 993 /** 994 * The method called when a camera device has encountered a serious error. 995 * 996 * <p>This callback may be called instead of {@link #onOpened} 997 * if opening the camera fails.</p> 998 * 999 * <p>This indicates a failure of the camera device or camera service in 1000 * some way. Any attempt to call methods on this CameraDevice in the 1001 * future will throw a {@link CameraAccessException} with the 1002 * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason. 1003 * </p> 1004 * 1005 * <p>There may still be capture completion or camera stream listeners 1006 * that will be called after this error is received.</p> 1007 * 1008 * <p>You should clean up the camera with {@link CameraDevice#close} after 1009 * this happens. Further attempts at recovery are error-code specific.</p> 1010 * 1011 * @param camera The device reporting the error 1012 * @param error The error code, one of the 1013 * {@code CameraDeviceListener.ERROR_*} values. 1014 * 1015 * @see #ERROR_CAMERA_DEVICE 1016 * @see #ERROR_CAMERA_SERVICE 1017 * @see #ERROR_CAMERA_DISABLED 1018 * @see #ERROR_CAMERA_IN_USE 1019 */ 1020 public abstract void onError(CameraDevice camera, int error); // Must implement 1021 } 1022 } 1023
