CameraDevice.java revision 53f91c5c260b25e4763efe52212c1cf404946e27
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.view.Surface; 20 21import java.lang.AutoCloseable; 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 * A basic template for direct application control of capture 91 * parameters. All automatic control is disabled (auto-exposure, auto-white 92 * balance, auto-focus), and post-processing parameters are set to preview 93 * quality. The manual capture parameters (exposure, sensitivity, and so on) 94 * are set to reasonable defaults, but should be overriden by the 95 * application depending on the intended use case. 96 * 97 * @see #createCaptureRequest 98 */ 99 public static final int TEMPLATE_MANUAL = 5; 100 101 /** 102 * Get the static properties for this camera. These are identical to the 103 * properties returned by {@link CameraManager#getCameraProperties}. 104 * 105 * @return the static properties of the camera. 106 * 107 * @throws CameraAccessException if the camera device is no longer connected 108 * 109 * @see CameraManager#getCameraProperties 110 */ 111 public CameraProperties getProperties() throws CameraAccessException; 112 /** 113 * <p>Set up a new output set of Surfaces for the camera device.</p> 114 * 115 * <p>The configuration determines the set of potential output Surfaces for 116 * the camera device for each capture request. A given request may use all 117 * or a only some of the outputs. This method must be called before requests 118 * can be submitted to the camera with {@link #capture capture}, 119 * {@link #captureBurst captureBurst}, 120 * {@link #setRepeatingRequest setRepeatingRequest}, or 121 * {@link #setRepeatingBurst setRepeatingBurst}.</p> 122 * 123 * <p>Surfaces suitable for inclusion as a camera output can be created for 124 * various use cases and targets:</p> 125 * 126 * <ul> 127 * 128 * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Set 129 * the size of the Surface with 130 * {@link android.view.SurfaceHolder#setFixedSize} to be one of the 131 * supported 132 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 133 * before calling {@link android.view.SurfaceHolder#getSurface}.</li> 134 * 135 * <li>For accessing through an OpenGL texture via a 136 * {@link android.graphics.SurfaceTexture SurfaceTexture}: Set the size of 137 * the SurfaceTexture with 138 * {@link android.graphics.SurfaceTexture#setDefaultBufferSize} to be one 139 * of the supported 140 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 141 * before creating a Surface from the SurfaceTexture with 142 * {@link Surface#Surface}.</li> 143 * 144 * <li>For recording with {@link android.media.MediaCodec}: Call 145 * {@link android.media.MediaCodec#createInputSurface} after configuring 146 * the media codec to use one of the 147 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes} 148 * </li> 149 * 150 * <li>For recording with {@link android.media.MediaRecorder}: TODO</li> 151 * 152 * <li>For efficient YUV processing with {@link android.renderscript}: 153 * Create a RenderScript 154 * {@link android.renderscript.Allocation Allocation} with a supported YUV 155 * type, the IO_INPUT flag, and one of the supported 156 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed sizes}. Then 157 * obtain the Surface with 158 * {@link android.renderscript.Allocation#getSurface}.</li> 159 * 160 * <li>For access to uncompressed, JPEG, or raw sensor data in the 161 * application: Create a {@link android.media.ImageReader} object with the 162 * desired {@link CameraProperties#SCALER_AVAILABLE_FORMATS image format}, 163 * and a size from the matching 164 * {@link CameraProperties#SCALER_AVAILABLE_PROCESSED_SIZES processed}, 165 * {@link CameraProperties#SCALER_AVAILABLE_JPEG_SIZES jpeg}, or 166 * {@link CameraProperties#SCALER_AVAILABLE_RAW_SIZES raw} sizes. Then 167 * obtain a Surface from it.</li> 168 * 169 * </ul> 170 * 171 * </p> 172 * 173 * <p>This function can take several hundred milliseconds to execute, since 174 * camera hardware may need to be powered on or reconfigured.</p> 175 * 176 * <p>The camera device will query each Surface's size and formats upon this 177 * call, so they must be set to a valid setting at this time (in particular: 178 * if the format is user-visible, it must be one of android.scaler.availableFormats; 179 * and the size must be one of android.scaler.available[Processed|Jpeg]Sizes).</p> 180 * 181 * <p>To change the configuration after requests have been submitted to the 182 * device, the camera device must be idle. To idle the device, stop any 183 * repeating requests with {@link #stopRepeating stopRepeating}, and then 184 * call {@link #waitUntilIdle waitUntilIdle}.</p> 185 * 186 * <p>Using larger resolution outputs, or more outputs, can result in slower 187 * output rate from the device.</p> 188 * 189 * @param outputs the new set of Surfaces that should be made available as 190 * targets for captured image data. 191 * 192 * @throws IllegalArgumentException if the set of output Surfaces do not 193 * meet the requirements 194 * @throws CameraAccessException if the camera device is no longer connected 195 * @throws IllegalStateException if the camera device is not idle, or has 196 * encountered a fatal error 197 */ 198 public void configureOutputs(List<Surface> outputs) throws CameraAccessException; 199 200 /** 201 * <p>Create a {@link CaptureRequest} initialized with template for a target 202 * use case. The settings are chosen to be the best options for the specific 203 * camera device, so it is not recommended to reuse the same request for a 204 * different camera device; create a request for that device and override 205 * the settings as desired, instead.</p> 206 * 207 * @param templateType An enumeration selecting the use case for this 208 * request; one of the CameraDevice.TEMPLATE_ values. 209 * @return a filled-in CaptureRequest, except for output streams. 210 * 211 * @throws IllegalArgumentException if the templateType is not in the list 212 * of supported templates. 213 * @throws CameraAccessException if the camera device is no longer connected 214 * @throws IllegalStateException if the camera device has been closed or the 215 * device has encountered a fatal error. 216 * 217 * @see #TEMPLATE_PREVIEW 218 * @see #TEMPLATE_RECORD 219 * @see #TEMPLATE_STILL_CAPTURE 220 * @see #TEMPLATE_VIDEO_SNAPSHOT 221 * @see #TEMPLATE_MANUAL 222 */ 223 public CaptureRequest createCaptureRequest(int templateType) 224 throws CameraAccessException; 225 226 /** 227 * <p>Submit a request for an image to be captured by this CameraDevice.</p> 228 * 229 * <p>The request defines all the parameters for capturing the single image, 230 * including sensor, lens, flash, and post-processing settings.</p> 231 * 232 * <p>Each request will produce one {@link CaptureResult} and produce new 233 * frames for one or more target Surfaces, as defined by the request's .</p> 234 * 235 * <p>Multiple requests can be in progress at once. They are processed in 236 * first-in, first-out order, with minimal delays between each 237 * capture. Requests submitted through this method have higher priority than 238 * those submitted through {@link #setRepeatingRequest} or 239 * {@link #setRepeatingBurst}, and will be processed as soon as the current 240 * repeat/repeatBurst processing completes.</p> 241 * 242 * @param request the settings for this capture. 243 * @param listener the callback object to notify once this request has been 244 * processed. If null, no metadata will be produced for this capture, 245 * although image data will still be produced. 246 * 247 * @throws CameraAccessException if the camera device is no longer connected 248 * @throws IllegalStateException if the camera device has been closed or the 249 * device has encountered a fatal error. 250 * 251 * @see #captureBurst 252 * @see #setRepeatingRequest 253 * @see #setRepeatingBurst 254 */ 255 public void capture(CaptureRequest request, CaptureListener listener) 256 throws CameraAccessException; 257 258 /** 259 * <p>Submit a list of requests to be captured in sequence as a burst. The 260 * burst will be captured in the minimum amount of time possible, and will 261 * not be interleaved with requests submitted by other capture or repeat 262 * calls.</p> 263 * 264 * <p>The requests will be captured in order, each capture producing one 265 * {@link CaptureResult} and frames for one or more 266 * target {@link android.view.Surface surfaces}.</p> 267 * 268 * <p>The main difference between this method and simply calling 269 * {@link #capture} repeatedly is that this method guarantees that no 270 * other requests will be interspersed with the burst.</p> 271 * 272 * @param requests the list of settings for this burst capture. 273 * @param listener the callback object to notify each time one of the 274 * requests in the burst has been processed. If null, no metadata will be 275 * produced for any requests in this burst, although image data will still 276 * be produced. 277 * 278 * @throws CameraAccessException if the camera device is no longer connected 279 * @throws IllegalStateException if the camera device has been closed or the 280 * device has encountered a fatal error. 281 * 282 * @see #capture 283 * @see #setRepeatingRequest 284 * @see #setRepeatingBurst 285 */ 286 public void captureBurst(List<CaptureRequest> requests, 287 CaptureListener listener) throws CameraAccessException; 288 289 /** 290 * <p>Request endlessly repeating capture of images by this 291 * CameraDevice.</p> 292 * 293 * <p>With this method, the CameraDevice will continually capture 294 * images using the settings in the provided {@link 295 * CaptureRequest}, at the maximum rate possible.</p> 296 * 297 * <p>Repeat requests have lower priority than those submitted 298 * through {@link #capture} or {@link #captureBurst}, so if 299 * capture() is called when a repeating request is active, the 300 * capture request will be processed before any further repeating 301 * requests are processed.<p> 302 * 303 * <p>Repeating requests are a simple way for an application to maintain a 304 * preview or other continuous stream of frames, without having to submit 305 * requests through {@link #capture} at video rates.</p> 306 * 307 * <p>To stop the repeating capture, call {@link #stopRepeating}</p> 308 * 309 * <p>Calling repeat will replace a burst set up by {@link 310 * #setRepeatingBurst}, although any in-progress burst will be 311 * completed before the new repeat request will be used.</p> 312 * 313 * @param request the request to repeat indefinitely 314 * @param listener the callback object to notify every time the 315 * request finishes processing. If null, no metadata will be 316 * produced for this stream of requests, although image data will 317 * still be produced. 318 * 319 * @throws CameraAccessException if the camera device is no longer 320 * connected 321 * @throws IllegalStateException if the camera device has been closed or the 322 * device has encountered a fatal error. 323 * 324 * @see #capture 325 * @see #captureBurst 326 * @see #setRepeatingBurst 327 */ 328 public void setRepeatingRequest(CaptureRequest request, CaptureListener listener) 329 throws CameraAccessException; 330 331 /** 332 * <p>Request endlessly repeating capture of a sequence of images by this 333 * CameraDevice.</p> 334 * 335 * <p>With this method, the CameraDevice will continually capture images, 336 * cycling through the settings in the provided list of 337 * {@link CaptureRequest CaptureRequests}, at the maximum rate possible.</p> 338 * 339 * <p>If a request is submitted through {@link #capture} or 340 * {@link #captureBurst}, the current repetition of the request list will be 341 * completed before the higher-priority request is handled. This guarantees 342 * that the application always receives a complete repeat burst captured in 343 * minimal time, instead of bursts interleaved with higher-priority 344 * captures, or incomplete captures.</p> 345 * 346 * <p>Repeating burst requests are a simple way for an application to 347 * maintain a preview or other continuous stream of frames where each 348 * request is different in a predicatable way, without having to submit 349 * requests through {@link #capture} at video rates.</p> 350 * 351 * <p>To stop the repeating capture, call {@link #stopRepeating}. Any 352 * ongoing burst will still be completed, however.</p> 353 * 354 * <p>Calling repeatBurst will replace a repeating request set up by 355 * {@link #setRepeatingRequest}, although any in-progress capture will be completed 356 * before the new repeat burst will be used.</p> 357 * 358 * @param requests the list of requests to cycle through indefinitely. 359 * @param listener the callback object to notify each time one of the 360 * requests in the repeating bursts has finished processing. If null, no 361 * metadata will be produced for this stream of requests, although image 362 * data will still be produced. 363 * 364 * @throws CameraAccessException if the camera device is no longer connected 365 * @throws IllegalStateException if the camera device has been closed or the 366 * device has encountered a fatal error. 367 * 368 * @see #capture 369 * @see #captureBurst 370 * @see #setRepeatingRequest 371 */ 372 public void setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener) 373 throws CameraAccessException; 374 375 /** 376 * <p>Cancel any ongoing repeating capture set by either 377 * {@link #setRepeatingRequest setRepeatingRequest} or 378 * {@link #setRepeatingBurst}. Has no effect on requests submitted through 379 * {@link #capture capture} or {@link #captureBurst captureBurst}.</p> 380 * 381 * <p>Any currently in-flight captures will still complete, as will any 382 * burst that is mid-capture. To ensure that the device has finished 383 * processing all of its capture requests and is in idle state, use the 384 * {@link #waitUntilIdle waitUntilIdle} method.</p> 385 * 386 * @throws CameraAccessException if the camera device is no longer connected 387 * @throws IllegalStateException if the camera device has been closed or the 388 * device has encountered a fatal error. 389 * 390 * @see #setRepeatingRequest 391 * @see #setRepeatingBurst 392 * @see #waitUntilIdle 393 * 394 * @throws CameraAccessException if the camera device is no longer connected 395 * @throws IllegalStateException if the camera device has been closed, the 396 * device has encountered a fatal error, or if there is an active repeating 397 * request or burst. 398 */ 399 public void stopRepeating() throws CameraAccessException; 400 401 /** 402 * <p>Wait until all the submitted requests have finished processing</p> 403 * 404 * <p>This method blocks until all the requests that have been submitted to 405 * the camera device, either through {@link #capture capture}, 406 * {@link #captureBurst captureBurst}, 407 * {@link #setRepeatingRequest setRepeatingRequest}, or 408 * {@link #setRepeatingBurst setRepeatingBurst}, have completed their 409 * processing.</p> 410 * 411 * <p>Once this call returns successfully, the device is in an idle state, 412 * and can be reconfigured with {@link #configureOutputs configureOutputs}.</p> 413 * 414 * <p>This method cannot be used if there is an active repeating request or 415 * burst, set with {@link #setRepeatingRequest setRepeatingRequest} or 416 * {@link #setRepeatingBurst setRepeatingBurst}. Call 417 * {@link #stopRepeating stopRepeating} before calling this method.</p> 418 * 419 * @throws CameraAccessException if the camera device is no longer connected 420 * @throws IllegalStateException if the camera device has been closed, the 421 * device has encountered a fatal error, or if there is an active repeating 422 * request or burst. 423 */ 424 public void waitUntilIdle() throws CameraAccessException; 425 426 /** 427 * Set the error listener object to call when an asynchronous error 428 * occurs. The errors reported here are only device-wide errors; errors 429 * about individual requests or frames are reported through 430 * {@link CaptureListener#onCaptureFailed}. 431 * 432 * @param listener the ErrorListener to send asynchronous error 433 * notifications to. Setting this to null will stop notifications about 434 * asynchronous errors. 435 */ 436 public void setErrorListener(ErrorListener listener); 437 438 /** 439 * Close the connection to this camera device. After this call, all calls to 440 * the camera device interface will throw a {@link IllegalStateException}, 441 * except for calls to close(). 442 * @throws Exception 443 */ 444 @Override 445 public void close() throws Exception; 446 // TODO: We should decide on the behavior of in-flight requests should be on close. 447 448 /** 449 * A listener for receiving metadata about completed image captures. The 450 * metadata includes, among other things, the final capture settings and the 451 * state of the control algorithms. 452 */ 453 public interface CaptureListener { 454 /** 455 * <p>Called when a capture request has been processed by a 456 * {@link CameraDevice}.</p> 457 * 458 * @param camera The CameraDevice sending the callback. 459 * @param request The request that was given to the CameraDevice 460 * @param result The output metadata from the capture, including the 461 * final capture parameters and the state of the camera system during 462 * capture. 463 * 464 * @see #capture 465 * @see #captureBurst 466 * @see #setRepeatingRequest 467 * @see #setRepeatingBurst 468 */ 469 public void onCaptureComplete(CameraDevice camera, 470 CaptureRequest request, CaptureResult result); 471 472 /** 473 * <p>Called instead of onCaptureComplete when the camera device failed 474 * to produce a CaptureResult for the request. Other requests are 475 * unaffected, and some or all image buffers from the capture may have 476 * been pushed to their respective output streams.</p> 477 * 478 * @param camera The CameraDevice sending the callback. 479 * @param request The request that was given to the CameraDevice 480 * 481 * @see #capture 482 * @see #captureBurst 483 * @see #setRepeatingRequest 484 * @see #setRepeatingBurst 485 */ 486 public void onCaptureFailed(CameraDevice camera, 487 CaptureRequest request); 488 } 489 490 /** 491 * <p>A listener for asynchronous errors from the camera device. Errors 492 * about specific {@link CaptureRequest CaptureRequests} are sent through 493 * the capture {@link CaptureListener#onCaptureFailed listener} 494 * interface. Errors reported through this listener affect the device as a 495 * whole.</p> 496 */ 497 public interface ErrorListener { 498 /** 499 * <p>This camera device has been disconnected by the camera 500 * service. Any attempt to call methods on this CameraDevice will throw 501 * a {@link CameraAccessException}. The disconnection could be due to a 502 * change in security policy or permissions; the physical disconnection 503 * of a removable camera device; or the camera being needed for a 504 * higher-priority use case.</p> 505 * 506 * <p>There may still be capture completion or camera stream listeners 507 * that will be called after this error is received.</p> 508 */ 509 public static final int DEVICE_DISCONNECTED = 1; 510 511 /** 512 * <p>The camera device has encountered a fatal error. Any attempt to 513 * call methods on this CameraDevice will throw a 514 * {@link java.lang.IllegalStateException}.</p> 515 * 516 * <p>There may still be capture completion or camera stream listeners 517 * that will be called after this error is received.</p> 518 * 519 * <p>The application needs to re-open the camera device to use it 520 * again.</p> 521 */ 522 public static final int DEVICE_ERROR = 2; 523 524 /** 525 * <p>The camera service has encountered a fatal error. Any attempt to 526 * call methods on this CameraDevice in the future will throw a 527 * {@link java.lang.IllegalStateException}.</p> 528 * 529 * <p>There may still be capture completion or camera stream listeners 530 * that will be called after this error is received.</p> 531 * 532 * <p>The device may need to be shut down and restarted to restore 533 * camera function, or there may be a persistent hardware problem.</p> 534 */ 535 public static final int SERVICE_ERROR = 3; 536 537 /** 538 * The method to call when a camera device has encountered an error. 539 * 540 * @param camera The device reporting the error 541 * @param error The error code, one of the ErrorListener.ERROR_ values. 542 */ 543 public void onCameraDeviceError(CameraDevice camera, int error); 544 } 545} 546