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