CameraDevice.java revision 126a7468c2b86f27779443f5f2578a03f3ad78e8
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.hardware.camera2.params.StreamConfigurationMap; 20import android.graphics.ImageFormat; 21import android.os.Handler; 22import android.view.Surface; 23 24import java.util.List; 25 26/** 27 * <p>The CameraDevice class is a representation of a single camera connected to an 28 * Android device, allowing for fine-grain control of image capture and 29 * post-processing at high frame rates.</p> 30 * 31 * <p>Your application must declare the 32 * {@link android.Manifest.permission#CAMERA Camera} permission in its manifest 33 * in order to access camera devices.</p> 34 * 35 * <p>A given camera device may provide support at one of two levels: limited or 36 * full. If a device only supports the limited level, then Camera2 exposes a 37 * feature set that is roughly equivalent to the older 38 * {@link android.hardware.Camera Camera} API, although with a cleaner and more 39 * efficient interface. Devices that implement the full level of support 40 * provide substantially improved capabilities over the older camera 41 * API. Applications that target the limited level devices will run unchanged on 42 * the full-level devices; if your application requires a full-level device for 43 * proper operation, declare the "android.hardware.camera2.full" feature in your 44 * manifest.</p> 45 * 46 * @see CameraManager#openCamera 47 * @see android.Manifest.permission#CAMERA 48 */ 49public abstract class CameraDevice implements AutoCloseable { 50 51 /** 52 * Create a request suitable for a camera preview window. Specifically, this 53 * means that high frame rate is given priority over the highest-quality 54 * post-processing. These requests would normally be used with the 55 * {@link CameraCaptureSession#setRepeatingRequest} method. 56 * 57 * @see #createCaptureRequest 58 */ 59 public static final int TEMPLATE_PREVIEW = 1; 60 61 /** 62 * Create a request suitable for still image capture. Specifically, this 63 * means prioritizing image quality over frame rate. These requests would 64 * commonly be used with the {@link CameraCaptureSession#capture} method. 65 * 66 * @see #createCaptureRequest 67 */ 68 public static final int TEMPLATE_STILL_CAPTURE = 2; 69 70 /** 71 * Create a request suitable for video recording. Specifically, this means 72 * that a stable frame rate is used, and post-processing is set for 73 * recording quality. These requests would commonly be used with the 74 * {@link CameraCaptureSession#setRepeatingRequest} method. 75 * 76 * @see #createCaptureRequest 77 */ 78 public static final int TEMPLATE_RECORD = 3; 79 80 /** 81 * Create a request suitable for still image capture while recording 82 * video. Specifically, this means maximizing image quality without 83 * disrupting the ongoing recording. These requests would commonly be used 84 * with the {@link CameraCaptureSession#capture} method while a request based on 85 * {@link #TEMPLATE_RECORD} is is in use with {@link CameraCaptureSession#setRepeatingRequest}. 86 * 87 * @see #createCaptureRequest 88 */ 89 public static final int TEMPLATE_VIDEO_SNAPSHOT = 4; 90 91 /** 92 * Create a request suitable for zero shutter lag still capture. This means 93 * means maximizing image quality without compromising preview frame rate. 94 * AE/AWB/AF should be on auto mode. 95 * 96 * @see #createCaptureRequest 97 */ 98 public static final int TEMPLATE_ZERO_SHUTTER_LAG = 5; 99 100 /** 101 * A basic template for direct application control of capture 102 * parameters. All automatic control is disabled (auto-exposure, auto-white 103 * balance, auto-focus), and post-processing parameters are set to preview 104 * quality. The manual capture parameters (exposure, sensitivity, and so on) 105 * are set to reasonable defaults, but should be overriden by the 106 * application depending on the intended use case. 107 * 108 * @see #createCaptureRequest 109 */ 110 public static final int TEMPLATE_MANUAL = 6; 111 112 /** 113 * Get the ID of this camera device. 114 * 115 * <p>This matches the ID given to {@link CameraManager#openCamera} to instantiate this 116 * this camera device.</p> 117 * 118 * <p>This ID can be used to query the camera device's {@link 119 * CameraCharacteristics fixed properties} with {@link 120 * CameraManager#getCameraCharacteristics}.</p> 121 * 122 * <p>This method can be called even if the device has been closed or has encountered 123 * a serious error.</p> 124 * 125 * @return the ID for this camera device 126 * 127 * @see CameraManager#getCameraCharacteristics 128 * @see CameraManager#getCameraIdList 129 */ 130 public abstract String getId(); 131 132 /** 133 * <p>Create a new camera capture session by providing the target output set of Surfaces to the 134 * camera device.</p> 135 * 136 * <p>The active capture session determines the set of potential output Surfaces for 137 * the camera device for each capture request. A given request may use all 138 * or a only some of the outputs. Once the CameraCaptureSession is created, requests can be 139 * can be submitted with {@link CameraCaptureSession#capture capture}, 140 * {@link CameraCaptureSession#captureBurst captureBurst}, 141 * {@link CameraCaptureSession#setRepeatingRequest setRepeatingRequest}, or 142 * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}.</p> 143 * 144 * <p>Surfaces suitable for inclusion as a camera output can be created for 145 * various use cases and targets:</p> 146 * 147 * <ul> 148 * 149 * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Once the SurfaceView's 150 * Surface is {@link android.view.SurfaceHolder.Callback#surfaceCreated created}, set the 151 * size of the Surface with {@link android.view.SurfaceHolder#setFixedSize} to be one of the 152 * sizes returned by 153 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(SurfaceHolder.class)} 154 * and then obtain the Surface by calling {@link android.view.SurfaceHolder#getSurface}.</li> 155 * 156 * <li>For accessing through an OpenGL texture via a 157 * {@link android.graphics.SurfaceTexture SurfaceTexture}: Set the size of 158 * the SurfaceTexture with 159 * {@link android.graphics.SurfaceTexture#setDefaultBufferSize} to be one 160 * of the sizes returned by 161 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(SurfaceTexture.class)} 162 * before creating a Surface from the SurfaceTexture with 163 * {@link Surface#Surface}.</li> 164 * 165 * <li>For recording with {@link android.media.MediaCodec}: Call 166 * {@link android.media.MediaCodec#createInputSurface} after configuring 167 * the media codec to use one of the sizes returned by 168 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaCodec.class)} 169 * </li> 170 * 171 * <li>For recording with {@link android.media.MediaRecorder}: Call 172 * {@link android.media.MediaRecorder#getSurface} after configuring the media recorder to use 173 * one of the sizes returned by 174 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaRecorder.class)}, 175 * or configuring it to use one of the supported 176 * {@link android.media.CamcorderProfile CamcorderProfiles}.</li> 177 * 178 * <li>For efficient YUV processing with {@link android.renderscript}: 179 * Create a RenderScript 180 * {@link android.renderscript.Allocation Allocation} with a supported YUV 181 * type, the IO_INPUT flag, and one of the sizes returned by 182 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(Allocation.class)}, 183 * Then obtain the Surface with 184 * {@link android.renderscript.Allocation#getSurface}.</li> 185 * 186 * <li>For access to raw, uncompressed JPEG data in the application: Create an 187 * {@link android.media.ImageReader} object with one of the supported output formats given by 188 * {@link StreamConfigurationMap#getOutputFormats()}, setting its size to one of the 189 * corresponding supported sizes by passing the chosen output format into 190 * {@link StreamConfigurationMap#getOutputSizes(int)}. Then obtain a 191 * {@link android.view.Surface} from it with {@link android.media.ImageReader#getSurface()}. 192 * </li> 193 * 194 * </ul> 195 * 196 * <p>The camera device will query each Surface's size and formats upon this 197 * call, so they must be set to a valid setting at this time.</p> 198 * 199 * <p>It can take several hundred milliseconds for the session's configuration to complete, 200 * since camera hardware may need to be powered on or reconfigured. Once the configuration is 201 * complete and the session is ready to actually capture data, the provided 202 * {@link CameraCaptureSession.StateCallback}'s 203 * {@link CameraCaptureSession.StateCallback#onConfigured} callback will be called.</p> 204 * 205 * <p>If a prior CameraCaptureSession already exists when a new one is created, the previous 206 * session is closed. Any in-progress capture requests made on the prior session will be 207 * completed before the new session is configured and is able to start capturing its own 208 * requests. To minimize the transition time, the {@link CameraCaptureSession#abortCaptures} 209 * call can be used to discard the remaining requests for the prior capture session before a new 210 * one is created. Note that once the new session is created, the old one can no longer have its 211 * captures aborted.</p> 212 * 213 * <p>Using larger resolution outputs, or more outputs, can result in slower 214 * output rate from the device.</p> 215 * 216 * <p>Configuring a session with an empty or null list will close the current session, if 217 * any. This can be used to release the current session's target surfaces for another use.</p> 218 * 219 * <p>While any of the sizes from {@link StreamConfigurationMap#getOutputSizes} can be used when 220 * a single output stream is configured, a given camera device may not be able to support all 221 * combination of sizes, formats, and targets when multiple outputs are configured at once. The 222 * tables below list the maximum guaranteed resolutions for combinations of streams and targets, 223 * given the capabilities of the camera device.</p> 224 * 225 * <p>If an application tries to create a session using a set of targets that exceed the limits 226 * described in the below tables, one of three possibilities may occur. First, the session may 227 * be successfully created and work normally. Second, the session may be successfully created, 228 * but the camera device won't meet the frame rate guarantees as described in 229 * {@link StreamConfigurationMap#getOutputMinFrameDuration}. Or third, if the output set 230 * cannot be used at all, session creation will fail entirely, with 231 * {@link CameraCaptureSession.StateListener#onConfigureFailed} being invoked.</p> 232 * 233 * <p>For the type column, {@code PRIV} refers to any target whose available sizes are found 234 * using {@link StreamConfigurationMap#getOutputSizes(Class)} with no direct application-visible 235 * format, {@code YUV} refers to a target Surface using the 236 * {@link android.graphics.ImageFormat#YUV_420_888} format, {@code JPEG} refers to the 237 * {@link android.graphics.ImageFormat#JPEG} format, and {@code RAW} refers to the 238 * {@link android.graphics.ImageFormat#RAW_SENSOR} format.</p> 239 * 240 * <p>For the maximum size column, {@code PREVIEW} refers to the best size match to the 241 * device's screen resolution, or to 1080p ({@code 1920x1080}), whichever is 242 * smaller. {@code RECORD} refers to the camera device's maximum supported recording resolution, 243 * as determined by {@link android.media.CamcorderProfile}. And {@code MAXIMUM} refers to the 244 * camera device's maximum output resolution for that format or target from 245 * {@link StreamConfigurationMap#getOutputSizes}.</p> 246 * 247 * <p>To use these tables, determine the number and the formats/targets of outputs needed, and 248 * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes 249 * that can be used; it is guaranteed that for those targets, the listed sizes and anything 250 * smaller from the list given by {@link StreamConfigurationMap#getOutputSizes} can be 251 * successfully used to create a session. For example, if a row indicates that a 8 megapixel 252 * (MP) YUV_420_888 output can be used together with a 2 MP {@code PRIV} output, then a session 253 * can be created with targets {@code [8 MP YUV, 2 MP PRIV]} or targets {@code [2 MP YUV, 2 MP 254 * PRIV]}; but a session with targets {@code [8 MP YUV, 4 MP PRIV]}, targets {@code [4 MP YUV, 4 255 * MP PRIV]}, or targets {@code [8 MP PRIV, 2 MP YUV]} would not be guaranteed to work, unless 256 * some other row of the table lists such a combination.</p> 257 * 258 * <style scoped> 259 * #rb { border-right-width: thick; } 260 * </style> 261 * <p>Legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 262 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at 263 * least the following stream combinations: 264 * 265 * <table> 266 * <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr> 267 * <tr> <th colspan="2" id="rb">Target 1</th> <th colspan="2" id="rb">Target 2</th> <th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 268 * <tr> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th></tr> 269 * <tr> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>Simple preview, GPU video processing, or no-preview video recording.</td> </tr> 270 * <tr> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-viewfinder still image capture.</td> </tr> 271 * <tr> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>In-application video/image processing.</td> </tr> 272 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Standard still imaging.</td> </tr> 273 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>In-app processing plus still capture.</td> </tr> 274 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td colspan="2" id="rb"></td> <td>Standard recording.</td> </tr> 275 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td colspan="2" id="rb"></td> <td>Preview plus in-app processing.</td> </tr> 276 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Still capture plus in-app processing.</td> </tr> 277 * </table><br> 278 * </p> 279 * 280 * <p>Limited-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 281 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices 282 * support at least the following stream combinations in addition to those for 283 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: 284 * 285 * <table> 286 * <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr> 287 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 288 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 289 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>High-resolution video recording with preview.</td> </tr> 290 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>High-resolution in-app video processing with preview.</td> </tr> 291 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td colspan="2" id="rb"></td> <td>Two-input in-app video processing.</td> </tr> 292 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code RECORD }</td> <td>{@code JPEG}</td><td id="rb">{@code RECORD }</td> <td>High-resolution recording with video snapshot.</td> </tr> 293 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code RECORD }</td> <td>{@code JPEG}</td><td id="rb">{@code RECORD }</td> <td>High-resolution in-app processing with video snapshot.</td> </tr> 294 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Two-input in-app processing with still capture.</td> </tr> 295 * </table><br> 296 * </p> 297 * 298 * <p>FULL-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 299 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices 300 * support at least the following stream combinations in addition to those for 301 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 302 * 303 * <table> 304 * <tr><th colspan="7">FULL-capability additional guaranteed configurations</th></tr> 305 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 306 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 307 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution GPU processing with preview.</td> </tr> 308 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution in-app processing with preview.</td> </tr> 309 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution two-input in-app processsing.</td> </tr> 310 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>Video recording with maximum-size video snapshot</td> </tr> 311 * <tr> <td>{@code YUV }</td><td id="rb">{@code 640x480}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Standard video recording plus maximum-resolution in-app processing.</td> </tr> 312 * <tr> <td>{@code YUV }</td><td id="rb">{@code 640x480}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Preview plus two-input maximum-resolution in-app processing.</td> </tr> 313 * </table><br> 314 * </p> 315 * 316 * <p>RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 317 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support 318 * at least the following stream combinations on both 319 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and 320 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 321 * 322 * <table> 323 * <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr> 324 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 325 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 326 * <tr> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-preview DNG capture.</td> </tr> 327 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>Standard DNG capture.</td> </tr> 328 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td colspan="2" id="rb"></td> <td>In-app processing plus DNG capture.</td> </tr> 329 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Video recording with DNG capture.</td> </tr> 330 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Preview with in-app processing and DNG capture.</td> </tr> 331 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Two-input in-app processing plus DNG capture.</td> </tr> 332 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>Still capture with simultaneous JPEG and DNG.</td> </tr> 333 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW }</td><td id="rb">{@code MAXIMUM}</td> <td>In-app processing with simultaneous JPEG and DNG.</td> </tr> 334 * </table><br> 335 * </p> 336 * 337 * <p>BURST-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 338 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices 339 * support at least the below stream combinations in addition to those for 340 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices. Note that all 341 * FULL-level devices support the BURST capability, and the below list is a strict subset of the 342 * list for FULL-level devices, so this table is only relevant for LIMITED-level devices that 343 * support the BURST_CAPTURE capability. 344 * 345 * <table> 346 * <tr><th colspan="5">BURST-capability additional guaranteed configurations</th></tr> 347 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th rowspan="2">Sample use case(s)</th> </tr> 348 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 349 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> <td>Maximum-resolution GPU processing with preview.</td> </tr> 350 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Maximum-resolution in-app processing with preview.</td> </tr> 351 * <tr> <td>{@code YUV }</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV }</td><td id="rb">{@code MAXIMUM}</td> <td>Maximum-resolution two-input in-app processsing.</td> </tr> 352 * </table><br> 353 * </p> 354 * 355 * <p>Since the capabilities of camera devices vary greatly, a given camera device may support 356 * target combinations with sizes outside of these guarantees, but this can only be tested for 357 * by attempting to create a session with such targets.</p> 358 * 359 * @param outputs The new set of Surfaces that should be made available as 360 * targets for captured image data. 361 * @param callback The callback to notify about the status of the new capture session. 362 * @param handler The handler on which the callback should be invoked, or {@code null} to use 363 * the current thread's {@link android.os.Looper looper}. 364 * 365 * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements, 366 * the callback is null, or the handler is null but the current 367 * thread has no looper. 368 * @throws CameraAccessException if the camera device is no longer connected or has 369 * encountered a fatal error 370 * @throws IllegalStateException if the camera device has been closed 371 * 372 * @see CameraCaptureSession 373 * @see StreamConfigurationMap#getOutputFormats() 374 * @see StreamConfigurationMap#getOutputSizes(int) 375 * @see StreamConfigurationMap#getOutputSizes(Class) 376 */ 377 public abstract void createCaptureSession(List<Surface> outputs, 378 CameraCaptureSession.StateCallback callback, Handler handler) 379 throws CameraAccessException; 380 381 /** 382 * <p>Create a {@link CaptureRequest.Builder} for new capture requests, 383 * initialized with template for a target use case. The settings are chosen 384 * to be the best options for the specific camera device, so it is not 385 * recommended to reuse the same request for a different camera device; 386 * create a builder specific for that device and template and override the 387 * settings as desired, instead.</p> 388 * 389 * @param templateType An enumeration selecting the use case for this 390 * request; one of the CameraDevice.TEMPLATE_ values. 391 * @return a builder for a capture request, initialized with default 392 * settings for that template, and no output streams 393 * 394 * @throws IllegalArgumentException if the templateType is not in the list 395 * of supported templates. 396 * @throws CameraAccessException if the camera device is no longer connected or has 397 * encountered a fatal error 398 * @throws IllegalStateException if the camera device has been closed 399 * 400 * @see #TEMPLATE_PREVIEW 401 * @see #TEMPLATE_RECORD 402 * @see #TEMPLATE_STILL_CAPTURE 403 * @see #TEMPLATE_VIDEO_SNAPSHOT 404 * @see #TEMPLATE_MANUAL 405 */ 406 public abstract CaptureRequest.Builder createCaptureRequest(int templateType) 407 throws CameraAccessException; 408 409 /** 410 * Close the connection to this camera device as quickly as possible. 411 * 412 * <p>Immediately after this call, all calls to the camera device or active session interface 413 * will throw a {@link IllegalStateException}, except for calls to close(). Once the device has 414 * fully shut down, the {@link StateCallback#onClosed} callback will be called, and the camera 415 * is free to be re-opened.</p> 416 * 417 * <p>Immediately after this call, besides the final {@link StateCallback#onClosed} calls, no 418 * further callbacks from the device or the active session will occur, and any remaining 419 * submitted capture requests will be discarded, as if 420 * {@link CameraCaptureSession#abortCaptures} had been called, except that no success or failure 421 * callbacks will be invoked.</p> 422 * 423 */ 424 @Override 425 public abstract void close(); 426 427 /** 428 * A callback objects for receiving updates about the state of a camera device. 429 * 430 * <p>A callback instance must be provided to the {@link CameraManager#openCamera} method to 431 * open a camera device.</p> 432 * 433 * <p>These state updates include notifications about the device completing startup ( 434 * allowing for {@link #createCaptureSession} to be called), about device 435 * disconnection or closure, and about unexpected device errors.</p> 436 * 437 * <p>Events about the progress of specific {@link CaptureRequest CaptureRequests} are provided 438 * through a {@link CameraCaptureSession.CaptureCallback} given to the 439 * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst}, 440 * {@link CameraCaptureSession#setRepeatingRequest}, or 441 * {@link CameraCaptureSession#setRepeatingBurst} methods. 442 * 443 * @see CameraManager#openCamera 444 */ 445 public static abstract class StateCallback { 446 /** 447 * An error code that can be reported by {@link #onError} 448 * indicating that the camera device is in use already. 449 * 450 * <p> 451 * This error can be produced when opening the camera fails. 452 * </p> 453 * 454 * @see #onError 455 */ 456 public static final int ERROR_CAMERA_IN_USE = 1; 457 458 /** 459 * An error code that can be reported by {@link #onError} 460 * indicating that the camera device could not be opened 461 * because there are too many other open camera devices. 462 * 463 * <p> 464 * The system-wide limit for number of open cameras has been reached, 465 * and more camera devices cannot be opened until previous instances are 466 * closed. 467 * </p> 468 * 469 * <p> 470 * This error can be produced when opening the camera fails. 471 * </p> 472 * 473 * @see #onError 474 */ 475 public static final int ERROR_MAX_CAMERAS_IN_USE = 2; 476 477 /** 478 * An error code that can be reported by {@link #onError} 479 * indicating that the camera device could not be opened due to a device 480 * policy. 481 * 482 * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) 483 * @see #onError 484 */ 485 public static final int ERROR_CAMERA_DISABLED = 3; 486 487 /** 488 * An error code that can be reported by {@link #onError} 489 * indicating that the camera device has encountered a fatal error. 490 * 491 * <p>The camera device needs to be re-opened to be used again.</p> 492 * 493 * @see #onError 494 */ 495 public static final int ERROR_CAMERA_DEVICE = 4; 496 497 /** 498 * An error code that can be reported by {@link #onError} 499 * indicating that the camera service has encountered a fatal error. 500 * 501 * <p>The Android device may need to be shut down and restarted to restore 502 * camera function, or there may be a persistent hardware problem.</p> 503 * 504 * <p>An attempt at recovery <i>may</i> be possible by closing the 505 * CameraDevice and the CameraManager, and trying to acquire all resources 506 * again from scratch.</p> 507 * 508 * @see #onError 509 */ 510 public static final int ERROR_CAMERA_SERVICE = 5; 511 512 /** 513 * The method called when a camera device has finished opening. 514 * 515 * <p>At this point, the camera device is ready to use, and 516 * {@link CameraDevice#createCaptureSession} can be called to set up the first capture 517 * session.</p> 518 * 519 * @param camera the camera device that has become opened 520 */ 521 public abstract void onOpened(CameraDevice camera); // Must implement 522 523 /** 524 * The method called when a camera device has been closed with 525 * {@link CameraDevice#close}. 526 * 527 * <p>Any attempt to call methods on this CameraDevice in the 528 * future will throw a {@link IllegalStateException}.</p> 529 * 530 * <p>The default implementation of this method does nothing.</p> 531 * 532 * @param camera the camera device that has become closed 533 */ 534 public void onClosed(CameraDevice camera) { 535 // Default empty implementation 536 } 537 538 /** 539 * The method called when a camera device is no longer available for 540 * use. 541 * 542 * <p>This callback may be called instead of {@link #onOpened} 543 * if opening the camera fails.</p> 544 * 545 * <p>Any attempt to call methods on this CameraDevice will throw a 546 * {@link CameraAccessException}. The disconnection could be due to a 547 * change in security policy or permissions; the physical disconnection 548 * of a removable camera device; or the camera being needed for a 549 * higher-priority use case.</p> 550 * 551 * <p>There may still be capture callbacks that are invoked 552 * after this method is called, or new image buffers that are delivered 553 * to active outputs.</p> 554 * 555 * <p>The default implementation logs a notice to the system log 556 * about the disconnection.</p> 557 * 558 * <p>You should clean up the camera with {@link CameraDevice#close} after 559 * this happens, as it is not recoverable until opening the camera again 560 * after it becomes {@link CameraManager.AvailabilityCallback#onCameraAvailable available}. 561 * </p> 562 * 563 * @param camera the device that has been disconnected 564 */ 565 public abstract void onDisconnected(CameraDevice camera); // Must implement 566 567 /** 568 * The method called when a camera device has encountered a serious error. 569 * 570 * <p>This callback may be called instead of {@link #onOpened} 571 * if opening the camera fails.</p> 572 * 573 * <p>This indicates a failure of the camera device or camera service in 574 * some way. Any attempt to call methods on this CameraDevice in the 575 * future will throw a {@link CameraAccessException} with the 576 * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason. 577 * </p> 578 * 579 * <p>There may still be capture completion or camera stream callbacks 580 * that will be called after this error is received.</p> 581 * 582 * <p>You should clean up the camera with {@link CameraDevice#close} after 583 * this happens. Further attempts at recovery are error-code specific.</p> 584 * 585 * @param camera The device reporting the error 586 * @param error The error code, one of the 587 * {@code StateCallback.ERROR_*} values. 588 * 589 * @see #ERROR_CAMERA_DEVICE 590 * @see #ERROR_CAMERA_SERVICE 591 * @see #ERROR_CAMERA_DISABLED 592 * @see #ERROR_CAMERA_IN_USE 593 */ 594 public abstract void onError(CameraDevice camera, int error); // Must implement 595 } 596 597 /** 598 * Temporary for migrating to Callback naming 599 * @hide 600 */ 601 public static abstract class StateListener extends StateCallback { 602 } 603 604 /** 605 * To be inherited by android.hardware.camera2.* code only. 606 * @hide 607 */ 608 public CameraDevice() {} 609} 610