Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 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.photography; |
| 18 | |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 19 | import android.view.Surface; |
| 20 | |
| 21 | import java.lang.AutoCloseable; |
| 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 | */ |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 47 | public interface CameraDevice extends AutoCloseable { |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 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 video recording. Specifically, this means |
| 61 | * that a stable frame rate is used, and post-processing is set for |
| 62 | * recording quality. These requests would commonly be used with the |
| 63 | * {@link #setRepeatingRequest} method. |
| 64 | * |
| 65 | * @see #createCaptureRequest |
| 66 | */ |
| 67 | public static final int TEMPLATE_RECORD = 2; |
| 68 | |
| 69 | /** |
| 70 | * Create a request suitable for still image capture. Specifically, this |
| 71 | * means prioritizing image quality over frame rate. These requests would |
| 72 | * commonly be used with the {@link #capture} method. |
| 73 | * |
| 74 | * @see #createCaptureRequest |
| 75 | */ |
| 76 | public static final int TEMPLATE_STILL_CAPTURE = 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 | */ |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 111 | public CameraProperties getProperties() throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 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>To change the configuration after requests have been submitted to the |
| 177 | * device, the camera device must be idle. To idle the device, stop any |
| 178 | * repeating requests with {@link #stopRepeating stopRepeating}, and then |
| 179 | * call {@link #waitUntilIdle waitUntilIdle}.</p> |
| 180 | * |
| 181 | * <p>Using larger resolution outputs, or more outputs, can result in slower |
| 182 | * output rate from the device.</p> |
| 183 | * |
| 184 | * @param outputs the new set of Surfaces that should be made available as |
| 185 | * targets for captured image data. |
| 186 | * |
| 187 | * @throws IllegalArgumentException if the set of output Surfaces do not |
| 188 | * meet the requirements |
| 189 | * @throws CameraAccessException if the camera device is no longer connected |
| 190 | * @throws IllegalStateException if the camera device is not idle, or has |
| 191 | * encountered a fatal error |
| 192 | */ |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 193 | public void configureOutputs(List<Surface> outputs) throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 194 | |
| 195 | /** |
| 196 | * <p>Create a {@link CaptureRequest} initialized with template for a target |
| 197 | * use case. The settings are chosen to be the best options for the specific |
| 198 | * camera device, so it is not recommended to reuse the same request for a |
| 199 | * different camera device; create a request for that device and override |
| 200 | * the settings as desired, instead.</p> |
| 201 | * |
| 202 | * @param templateType An enumeration selecting the use case for this |
| 203 | * request; one of the CameraDevice.TEMPLATE_ values. |
| 204 | * @return a filled-in CaptureRequest, except for output streams. |
| 205 | * |
| 206 | * @throws IllegalArgumentException if the templateType is not in the list |
| 207 | * of supported templates. |
| 208 | * @throws CameraAccessException if the camera device is no longer connected |
| 209 | * @throws IllegalStateException if the camera device has been closed or the |
| 210 | * device has encountered a fatal error. |
| 211 | * |
| 212 | * @see #TEMPLATE_PREVIEW |
| 213 | * @see #TEMPLATE_RECORD |
| 214 | * @see #TEMPLATE_STILL_CAPTURE |
| 215 | * @see #TEMPLATE_VIDEO_SNAPSHOT |
| 216 | * @see #TEMPLATE_MANUAL |
| 217 | */ |
| 218 | public CaptureRequest createCaptureRequest(int templateType) |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 219 | throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 220 | |
| 221 | /** |
| 222 | * <p>Submit a request for an image to be captured by this CameraDevice.</p> |
| 223 | * |
| 224 | * <p>The request defines all the parameters for capturing the single image, |
| 225 | * including sensor, lens, flash, and post-processing settings.</p> |
| 226 | * |
| 227 | * <p>Each request will produce one {@link CaptureResult} and produce new |
| 228 | * frames for one or more target Surfaces, as defined by the request's .</p> |
| 229 | * |
| 230 | * <p>Multiple requests can be in progress at once. They are processed in |
| 231 | * first-in, first-out order, with minimal delays between each |
| 232 | * capture. Requests submitted through this method have higher priority than |
| 233 | * those submitted through {@link #setRepeatingRequest} or |
| 234 | * {@link #setRepeatingBurst}, and will be processed as soon as the current |
| 235 | * repeat/repeatBurst processing completes.</p> |
| 236 | * |
| 237 | * @param request the settings for this capture. |
| 238 | * @param listener the callback object to notify once this request has been |
| 239 | * processed. If null, no metadata will be produced for this capture, |
| 240 | * although image data will still be produced. |
| 241 | * |
| 242 | * @throws CameraAccessException if the camera device is no longer connected |
| 243 | * @throws IllegalStateException if the camera device has been closed or the |
| 244 | * device has encountered a fatal error. |
| 245 | * |
| 246 | * @see #captureBurst |
| 247 | * @see #setRepeatingRequest |
| 248 | * @see #setRepeatingBurst |
| 249 | */ |
| 250 | public void capture(CaptureRequest request, CaptureListener listener) |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 251 | throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 252 | |
| 253 | /** |
| 254 | * <p>Submit a list of requests to be captured in sequence as a burst. The |
| 255 | * burst will be captured in the minimum amount of time possible, and will |
| 256 | * not be interleaved with requests submitted by other capture or repeat |
| 257 | * calls.</p> |
| 258 | * |
| 259 | * <p>The requests will be captured in order, each capture producing one |
| 260 | * {@link CaptureResult} and frames for one or more |
| 261 | * target {@link android.view.Surface surfaces}.</p> |
| 262 | * |
| 263 | * <p>The main difference between this method and simply calling |
| 264 | * {@link #capture} repeatedly is that this method guarantees that no |
| 265 | * other requests will be interspersed with the burst.</p> |
| 266 | * |
| 267 | * @param requests the list of settings for this burst capture. |
| 268 | * @param listener the callback object to notify each time one of the |
| 269 | * requests in the burst has been processed. If null, no metadata will be |
| 270 | * produced for any requests in this burst, although image data will still |
| 271 | * be produced. |
| 272 | * |
| 273 | * @throws CameraAccessException if the camera device is no longer connected |
| 274 | * @throws IllegalStateException if the camera device has been closed or the |
| 275 | * device has encountered a fatal error. |
| 276 | * |
| 277 | * @see #capture |
| 278 | * @see #setRepeatingRequest |
| 279 | * @see #setRepeatingBurst |
| 280 | */ |
| 281 | public void captureBurst(List<CaptureRequest> requests, |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 282 | CaptureListener listener) throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 283 | |
| 284 | /** |
| 285 | * <p>Request endlessly repeating capture of images by this |
| 286 | * CameraDevice.</p> |
| 287 | * |
| 288 | * <p>With this method, the CameraDevice will continually capture |
| 289 | * images using the settings in the provided {@link |
| 290 | * CaptureRequest}, at the maximum rate possible.</p> |
| 291 | * |
| 292 | * <p>Repeat requests have lower priority than those submitted |
| 293 | * through {@link #capture} or {@link #captureBurst}, so if |
| 294 | * capture() is called when a repeating request is active, the |
| 295 | * capture request will be processed before any further repeating |
| 296 | * requests are processed.<p> |
| 297 | * |
| 298 | * <p>Repeating requests are a simple way for an application to maintain a |
| 299 | * preview or other continuous stream of frames, without having to submit |
| 300 | * requests through {@link #capture} at video rates.</p> |
| 301 | * |
| 302 | * <p>To stop the repeating capture, call {@link #stopRepeating}</p> |
| 303 | * |
| 304 | * <p>Calling repeat will replace a burst set up by {@link |
| 305 | * #setRepeatingBurst}, although any in-progress burst will be |
| 306 | * completed before the new repeat request will be used.</p> |
| 307 | * |
| 308 | * @param request the request to repeat indefinitely |
| 309 | * @param listener the callback object to notify every time the |
| 310 | * request finishes processing. If null, no metadata will be |
| 311 | * produced for this stream of requests, although image data will |
| 312 | * still be produced. |
| 313 | * |
| 314 | * @throws CameraAccessException if the camera device is no longer |
| 315 | * connected |
| 316 | * @throws IllegalStateException if the camera device has been closed or the |
| 317 | * device has encountered a fatal error. |
| 318 | * |
| 319 | * @see #capture |
| 320 | * @see #captureBurst |
| 321 | * @see #setRepeatingBurst |
| 322 | */ |
| 323 | public void setRepeatingRequest(CaptureRequest request, CaptureListener listener) |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 324 | throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 325 | |
| 326 | /** |
| 327 | * <p>Request endlessly repeating capture of a sequence of images by this |
| 328 | * CameraDevice.</p> |
| 329 | * |
| 330 | * <p>With this method, the CameraDevice will continually capture images, |
| 331 | * cycling through the settings in the provided list of |
| 332 | * {@link CaptureRequest CaptureRequests}, at the maximum rate possible.</p> |
| 333 | * |
| 334 | * <p>If a request is submitted through {@link #capture} or |
| 335 | * {@link #captureBurst}, the current repetition of the request list will be |
| 336 | * completed before the higher-priority request is handled. This guarantees |
| 337 | * that the application always receives a complete repeat burst captured in |
| 338 | * minimal time, instead of bursts interleaved with higher-priority |
| 339 | * captures, or incomplete captures.</p> |
| 340 | * |
| 341 | * <p>Repeating burst requests are a simple way for an application to |
| 342 | * maintain a preview or other continuous stream of frames where each |
| 343 | * request is different in a predicatable way, without having to submit |
| 344 | * requests through {@link #capture} at video rates.</p> |
| 345 | * |
| 346 | * <p>To stop the repeating capture, call {@link #stopRepeating}. Any |
| 347 | * ongoing burst will still be completed, however.</p> |
| 348 | * |
| 349 | * <p>Calling repeatBurst will replace a repeating request set up by |
| 350 | * {@link #setRepeatingRequest}, although any in-progress capture will be completed |
| 351 | * before the new repeat burst will be used.</p> |
| 352 | * |
| 353 | * @param requests the list of requests to cycle through indefinitely. |
| 354 | * @param listener the callback object to notify each time one of the |
| 355 | * requests in the repeating bursts has finished processing. If null, no |
| 356 | * metadata will be produced for this stream of requests, although image |
| 357 | * data will still be produced. |
| 358 | * |
| 359 | * @throws CameraAccessException if the camera device is no longer connected |
| 360 | * @throws IllegalStateException if the camera device has been closed or the |
| 361 | * device has encountered a fatal error. |
| 362 | * |
| 363 | * @see #capture |
| 364 | * @see #captureBurst |
| 365 | * @see #setRepeatingRequest |
| 366 | */ |
| 367 | public void setRepeatingBurst(List<CaptureRequest> requests, CaptureListener listener) |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 368 | throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 369 | |
| 370 | /** |
| 371 | * <p>Cancel any ongoing repeating capture set by either |
| 372 | * {@link #setRepeatingRequest setRepeatingRequest} or |
| 373 | * {@link #setRepeatingBurst}. Has no effect on requests submitted through |
| 374 | * {@link #capture capture} or {@link #captureBurst captureBurst}.</p> |
| 375 | * |
| 376 | * <p>Any currently in-flight captures will still complete, as will any |
| 377 | * burst that is mid-capture. To ensure that the device has finished |
| 378 | * processing all of its capture requests and is in idle state, use the |
| 379 | * {@link #waitUntilIdle waitUntilIdle} method.</p> |
| 380 | * |
| 381 | * @throws CameraAccessException if the camera device is no longer connected |
| 382 | * @throws IllegalStateException if the camera device has been closed or the |
| 383 | * device has encountered a fatal error. |
| 384 | * |
| 385 | * @see #setRepeatingRequest |
| 386 | * @see #setRepeatingBurst |
| 387 | * @see #waitUntilIdle |
| 388 | * |
| 389 | * @throws CameraAccessException if the camera device is no longer connected |
| 390 | * @throws IllegalStateException if the camera device has been closed, the |
| 391 | * device has encountered a fatal error, or if there is an active repeating |
| 392 | * request or burst. |
| 393 | */ |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 394 | public void stopRepeating() throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 395 | |
| 396 | /** |
| 397 | * <p>Wait until all the submitted requests have finished processing</p> |
| 398 | * |
| 399 | * <p>This method blocks until all the requests that have been submitted to |
| 400 | * the camera device, either through {@link #capture capture}, |
| 401 | * {@link #captureBurst captureBurst}, |
| 402 | * {@link #setRepeatingRequest setRepeatingRequest}, or |
| 403 | * {@link #setRepeatingBurst setRepeatingBurst}, have completed their |
| 404 | * processing.</p> |
| 405 | * |
| 406 | * <p>Once this call returns successfully, the device is in an idle state, |
| 407 | * and can be reconfigured with {@link #configureOutputs configureOutputs}.</p> |
| 408 | * |
| 409 | * <p>This method cannot be used if there is an active repeating request or |
| 410 | * burst, set with {@link #setRepeatingRequest setRepeatingRequest} or |
| 411 | * {@link #setRepeatingBurst setRepeatingBurst}. Call |
| 412 | * {@link #stopRepeating stopRepeating} before calling this method.</p> |
| 413 | * |
| 414 | * @throws CameraAccessException if the camera device is no longer connected |
| 415 | * @throws IllegalStateException if the camera device has been closed, the |
| 416 | * device has encountered a fatal error, or if there is an active repeating |
| 417 | * request or burst. |
| 418 | */ |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 419 | public void waitUntilIdle() throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 420 | |
| 421 | /** |
| 422 | * Set the error listener object to call when an asynchronous error |
| 423 | * occurs. The errors reported here are only device-wide errors; errors |
| 424 | * about individual requests or frames are reported through |
| 425 | * {@link CaptureListener#onCaptureFailed}. |
| 426 | * |
| 427 | * @param listener the ErrorListener to send asynchronous error |
| 428 | * notifications to. Setting this to null will stop notifications about |
| 429 | * asynchronous errors. |
| 430 | */ |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 431 | public void setErrorListener(ErrorListener listener); |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 432 | |
| 433 | /** |
| 434 | * Close the connection to this camera device. After this call, all calls to |
| 435 | * the camera device interface will throw a {@link IllegalStateException}, |
| 436 | * except for calls to close(). |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 437 | * @throws Exception |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 438 | */ |
Igor Murashkin | e363fbb | 2013-06-25 20:26:06 +0000 | [diff] [blame] | 439 | @Override |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame^] | 440 | public void close() throws Exception; |
| 441 | // TODO: We should decide on the behavior of in-flight requests should be on close. |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 442 | |
| 443 | /** |
| 444 | * A listener for receiving metadata about completed image captures. The |
| 445 | * metadata includes, among other things, the final capture settings and the |
| 446 | * state of the control algorithms. |
| 447 | */ |
| 448 | public interface CaptureListener { |
| 449 | /** |
| 450 | * <p>Called when a capture request has been processed by a |
| 451 | * {@link CameraDevice}.</p> |
| 452 | * |
| 453 | * @param camera The CameraDevice sending the callback. |
| 454 | * @param request The request that was given to the CameraDevice |
| 455 | * @param result The output metadata from the capture, including the |
| 456 | * final capture parameters and the state of the camera system during |
| 457 | * capture. |
| 458 | * |
| 459 | * @see #capture |
| 460 | * @see #captureBurst |
| 461 | * @see #setRepeatingRequest |
| 462 | * @see #setRepeatingBurst |
| 463 | */ |
| 464 | public void onCaptureComplete(CameraDevice camera, |
| 465 | CaptureRequest request, CaptureResult result); |
| 466 | |
| 467 | /** |
| 468 | * <p>Called instead of onCaptureComplete when the camera device failed |
| 469 | * to produce a CaptureResult for the request. Other requests are |
| 470 | * unaffected, and some or all image buffers from the capture may have |
| 471 | * been pushed to their respective output streams.</p> |
| 472 | * |
| 473 | * @param camera The CameraDevice sending the callback. |
| 474 | * @param request The request that was given to the CameraDevice |
| 475 | * |
| 476 | * @see #capture |
| 477 | * @see #captureBurst |
| 478 | * @see #setRepeatingRequest |
| 479 | * @see #setRepeatingBurst |
| 480 | */ |
| 481 | public void onCaptureFailed(CameraDevice camera, |
| 482 | CaptureRequest request); |
| 483 | } |
| 484 | |
| 485 | /** |
| 486 | * <p>A listener for asynchronous errors from the camera device. Errors |
| 487 | * about specific {@link CaptureRequest CaptureRequests} are sent through |
| 488 | * the capture {@link CaptureListener#onCaptureFailed listener} |
| 489 | * interface. Errors reported through this listener affect the device as a |
| 490 | * whole.</p> |
| 491 | */ |
| 492 | public interface ErrorListener { |
| 493 | /** |
| 494 | * <p>This camera device has been disconnected by the camera |
| 495 | * service. Any attempt to call methods on this CameraDevice will throw |
| 496 | * a {@link CameraAccessException}. The disconnection could be due to a |
| 497 | * change in security policy or permissions; the physical disconnection |
| 498 | * of a removable camera device; or the camera being needed for a |
| 499 | * higher-priority use case.</p> |
| 500 | * |
| 501 | * <p>There may still be capture completion or camera stream listeners |
| 502 | * that will be called after this error is received.</p> |
| 503 | */ |
| 504 | public static final int DEVICE_DISCONNECTED = 1; |
| 505 | |
| 506 | /** |
| 507 | * <p>The camera device has encountered a fatal error. Any attempt to |
| 508 | * call methods on this CameraDevice will throw a |
| 509 | * {@link java.lang.IllegalStateException}.</p> |
| 510 | * |
| 511 | * <p>There may still be capture completion or camera stream listeners |
| 512 | * that will be called after this error is received.</p> |
| 513 | * |
| 514 | * <p>The application needs to re-open the camera device to use it |
| 515 | * again.</p> |
| 516 | */ |
| 517 | public static final int DEVICE_ERROR = 2; |
| 518 | |
| 519 | /** |
| 520 | * <p>The camera service has encountered a fatal error. Any attempt to |
| 521 | * call methods on this CameraDevice in the future will throw a |
| 522 | * {@link java.lang.IllegalStateException}.</p> |
| 523 | * |
| 524 | * <p>There may still be capture completion or camera stream listeners |
| 525 | * that will be called after this error is received.</p> |
| 526 | * |
| 527 | * <p>The device may need to be shut down and restarted to restore |
| 528 | * camera function, or there may be a persistent hardware problem.</p> |
| 529 | */ |
| 530 | public static final int SERVICE_ERROR = 3; |
| 531 | |
| 532 | /** |
| 533 | * The method to call when a camera device has encountered an error. |
| 534 | * |
| 535 | * @param camera The device reporting the error |
| 536 | * @param error The error code, one of the ErrorListener.ERROR_ values. |
| 537 | */ |
| 538 | public void onCameraDeviceError(CameraDevice camera, int error); |
| 539 | } |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 540 | } |