1 /* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.camera2; 18 19 import android.hardware.camera2.params.StreamConfigurationMap; 20 import android.graphics.ImageFormat; 21 import android.os.Handler; 22 import android.view.Surface; 23 24 import 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 */ 49 public 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 */ getId()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 size 151 * of the Surface with {@link android.view.SurfaceHolder#setFixedSize} to be one of the sizes 152 * returned by {@link StreamConfigurationMap#getOutputSizes(Class) 153 * getOutputSizes(SurfaceHolder.class)} and then obtain the Surface by calling {@link 154 * android.view.SurfaceHolder#getSurface}. If the size is not set by the application, it will 155 * be rounded to the nearest supported size less than 1080p, by the camera device.</li> 156 * 157 * <li>For accessing through an OpenGL texture via a {@link android.graphics.SurfaceTexture 158 * SurfaceTexture}: Set the size of the SurfaceTexture with {@link 159 * android.graphics.SurfaceTexture#setDefaultBufferSize} to be one of the sizes returned by 160 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(SurfaceTexture.class)} 161 * before creating a Surface from the SurfaceTexture with {@link Surface#Surface}. If the size 162 * is not set by the application, it will be set to be the smallest supported size less than 163 * 1080p, by the camera device.</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 * If the ImageReader size is not set to a supported size, it will be rounded to a supported 193 * size less than 1080p by the camera device. 194 * </li> 195 * 196 * </ul> 197 * 198 * <p>The camera device will query each Surface's size and formats upon this 199 * call, so they must be set to a valid setting at this time.</p> 200 * 201 * <p>It can take several hundred milliseconds for the session's configuration to complete, 202 * since camera hardware may need to be powered on or reconfigured. Once the configuration is 203 * complete and the session is ready to actually capture data, the provided 204 * {@link CameraCaptureSession.StateCallback}'s 205 * {@link CameraCaptureSession.StateCallback#onConfigured} callback will be called.</p> 206 * 207 * <p>If a prior CameraCaptureSession already exists when a new one is created, the previous 208 * session is closed. Any in-progress capture requests made on the prior session will be 209 * completed before the new session is configured and is able to start capturing its own 210 * requests. To minimize the transition time, the {@link CameraCaptureSession#abortCaptures} 211 * call can be used to discard the remaining requests for the prior capture session before a new 212 * one is created. Note that once the new session is created, the old one can no longer have its 213 * captures aborted.</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 a session with an empty or null list will close the current session, if 219 * any. This can be used to release the current session's target surfaces for another use.</p> 220 * 221 * <p>While any of the sizes from {@link StreamConfigurationMap#getOutputSizes} can be used when 222 * a single output stream is configured, a given camera device may not be able to support all 223 * combination of sizes, formats, and targets when multiple outputs are configured at once. The 224 * tables below list the maximum guaranteed resolutions for combinations of streams and targets, 225 * given the capabilities of the camera device.</p> 226 * 227 * <p>If an application tries to create a session using a set of targets that exceed the limits 228 * described in the below tables, one of three possibilities may occur. First, the session may 229 * be successfully created and work normally. Second, the session may be successfully created, 230 * but the camera device won't meet the frame rate guarantees as described in 231 * {@link StreamConfigurationMap#getOutputMinFrameDuration}. Or third, if the output set 232 * cannot be used at all, session creation will fail entirely, with 233 * {@link CameraCaptureSession.StateListener#onConfigureFailed} being invoked.</p> 234 * 235 * <p>For the type column, {@code PRIV} refers to any target whose available sizes are found 236 * using {@link StreamConfigurationMap#getOutputSizes(Class)} with no direct application-visible 237 * format, {@code YUV} refers to a target Surface using the 238 * {@link android.graphics.ImageFormat#YUV_420_888} format, {@code JPEG} refers to the 239 * {@link android.graphics.ImageFormat#JPEG} format, and {@code RAW} refers to the 240 * {@link android.graphics.ImageFormat#RAW_SENSOR} format.</p> 241 * 242 * <p>For the maximum size column, {@code PREVIEW} refers to the best size match to the 243 * device's screen resolution, or to 1080p ({@code 1920x1080}), whichever is 244 * smaller. {@code RECORD} refers to the camera device's maximum supported recording resolution, 245 * as determined by {@link android.media.CamcorderProfile}. And {@code MAXIMUM} refers to the 246 * camera device's maximum output resolution for that format or target from 247 * {@link StreamConfigurationMap#getOutputSizes}.</p> 248 * 249 * <p>To use these tables, determine the number and the formats/targets of outputs needed, and 250 * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes 251 * that can be used; it is guaranteed that for those targets, the listed sizes and anything 252 * smaller from the list given by {@link StreamConfigurationMap#getOutputSizes} can be 253 * successfully used to create a session. For example, if a row indicates that a 8 megapixel 254 * (MP) YUV_420_888 output can be used together with a 2 MP {@code PRIV} output, then a session 255 * can be created with targets {@code [8 MP YUV, 2 MP PRIV]} or targets {@code [2 MP YUV, 2 MP 256 * PRIV]}; but a session with targets {@code [8 MP YUV, 4 MP PRIV]}, targets {@code [4 MP YUV, 4 257 * MP PRIV]}, or targets {@code [8 MP PRIV, 2 MP YUV]} would not be guaranteed to work, unless 258 * some other row of the table lists such a combination.</p> 259 * 260 * <style scoped> 261 * #rb { border-right-width: thick; } 262 * </style> 263 * <p>Legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 264 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at 265 * least the following stream combinations: 266 * 267 * <table> 268 * <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr> 269 * <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> 270 * <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> 271 * <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> 272 * <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> 273 * <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> 274 * <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> 275 * <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> 276 * <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> 277 * <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> 278 * <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> 279 * </table><br> 280 * </p> 281 * 282 * <p>Limited-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 283 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices 284 * support at least the following stream combinations in addition to those for 285 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: 286 * 287 * <table> 288 * <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr> 289 * <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> 290 * <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> 291 * <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> 292 * <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> 293 * <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> 294 * <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> 295 * <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> 296 * <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> 297 * </table><br> 298 * </p> 299 * 300 * <p>FULL-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 301 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices 302 * support at least the following stream combinations in addition to those for 303 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 304 * 305 * <table> 306 * <tr><th colspan="7">FULL-capability additional guaranteed configurations</th></tr> 307 * <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> 308 * <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> 309 * <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> 310 * <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> 311 * <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> 312 * <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> 313 * <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> 314 * <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> 315 * </table><br> 316 * </p> 317 * 318 * <p>RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 319 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support 320 * at least the following stream combinations on both 321 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and 322 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 323 * 324 * <table> 325 * <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr> 326 * <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> 327 * <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> 328 * <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> 329 * <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> 330 * <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> 331 * <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> 332 * <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> 333 * <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> 334 * <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> 335 * <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> 336 * </table><br> 337 * </p> 338 * 339 * <p>BURST-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 340 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices 341 * support at least the below stream combinations in addition to those for 342 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices. Note that all 343 * FULL-level devices support the BURST capability, and the below list is a strict subset of the 344 * list for FULL-level devices, so this table is only relevant for LIMITED-level devices that 345 * support the BURST_CAPTURE capability. 346 * 347 * <table> 348 * <tr><th colspan="5">BURST-capability additional guaranteed configurations</th></tr> 349 * <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> 350 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 351 * <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> 352 * <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> 353 * <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> 354 * </table><br> 355 * </p> 356 * 357 * <p>Since the capabilities of camera devices vary greatly, a given camera device may support 358 * target combinations with sizes outside of these guarantees, but this can only be tested for 359 * by attempting to create a session with such targets.</p> 360 * 361 * @param outputs The new set of Surfaces that should be made available as 362 * targets for captured image data. 363 * @param callback The callback to notify about the status of the new capture session. 364 * @param handler The handler on which the callback should be invoked, or {@code null} to use 365 * the current thread's {@link android.os.Looper looper}. 366 * 367 * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements, 368 * the callback is null, or the handler is null but the current 369 * thread has no looper. 370 * @throws CameraAccessException if the camera device is no longer connected or has 371 * encountered a fatal error 372 * @throws IllegalStateException if the camera device has been closed 373 * 374 * @see CameraCaptureSession 375 * @see StreamConfigurationMap#getOutputFormats() 376 * @see StreamConfigurationMap#getOutputSizes(int) 377 * @see StreamConfigurationMap#getOutputSizes(Class) 378 */ createCaptureSession(List<Surface> outputs, CameraCaptureSession.StateCallback callback, Handler handler)379 public abstract void createCaptureSession(List<Surface> outputs, 380 CameraCaptureSession.StateCallback callback, Handler handler) 381 throws CameraAccessException; 382 383 /** 384 * <p>Create a {@link CaptureRequest.Builder} for new capture requests, 385 * initialized with template for a target use case. The settings are chosen 386 * to be the best options for the specific camera device, so it is not 387 * recommended to reuse the same request for a different camera device; 388 * create a builder specific for that device and template and override the 389 * settings as desired, instead.</p> 390 * 391 * @param templateType An enumeration selecting the use case for this 392 * request; one of the CameraDevice.TEMPLATE_ values. 393 * @return a builder for a capture request, initialized with default 394 * settings for that template, and no output streams 395 * 396 * @throws IllegalArgumentException if the templateType is not in the list 397 * of supported templates. 398 * @throws CameraAccessException if the camera device is no longer connected or has 399 * encountered a fatal error 400 * @throws IllegalStateException if the camera device has been closed 401 * 402 * @see #TEMPLATE_PREVIEW 403 * @see #TEMPLATE_RECORD 404 * @see #TEMPLATE_STILL_CAPTURE 405 * @see #TEMPLATE_VIDEO_SNAPSHOT 406 * @see #TEMPLATE_MANUAL 407 */ createCaptureRequest(int templateType)408 public abstract CaptureRequest.Builder createCaptureRequest(int templateType) 409 throws CameraAccessException; 410 411 /** 412 * Close the connection to this camera device as quickly as possible. 413 * 414 * <p>Immediately after this call, all calls to the camera device or active session interface 415 * will throw a {@link IllegalStateException}, except for calls to close(). Once the device has 416 * fully shut down, the {@link StateCallback#onClosed} callback will be called, and the camera 417 * is free to be re-opened.</p> 418 * 419 * <p>Immediately after this call, besides the final {@link StateCallback#onClosed} calls, no 420 * further callbacks from the device or the active session will occur, and any remaining 421 * submitted capture requests will be discarded, as if 422 * {@link CameraCaptureSession#abortCaptures} had been called, except that no success or failure 423 * callbacks will be invoked.</p> 424 * 425 */ 426 @Override close()427 public abstract void close(); 428 429 /** 430 * A callback objects for receiving updates about the state of a camera device. 431 * 432 * <p>A callback instance must be provided to the {@link CameraManager#openCamera} method to 433 * open a camera device.</p> 434 * 435 * <p>These state updates include notifications about the device completing startup ( 436 * allowing for {@link #createCaptureSession} to be called), about device 437 * disconnection or closure, and about unexpected device errors.</p> 438 * 439 * <p>Events about the progress of specific {@link CaptureRequest CaptureRequests} are provided 440 * through a {@link CameraCaptureSession.CaptureCallback} given to the 441 * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst}, 442 * {@link CameraCaptureSession#setRepeatingRequest}, or 443 * {@link CameraCaptureSession#setRepeatingBurst} methods. 444 * 445 * @see CameraManager#openCamera 446 */ 447 public static abstract class StateCallback { 448 /** 449 * An error code that can be reported by {@link #onError} 450 * indicating that the camera device is in use already. 451 * 452 * <p> 453 * This error can be produced when opening the camera fails. 454 * </p> 455 * 456 * @see #onError 457 */ 458 public static final int ERROR_CAMERA_IN_USE = 1; 459 460 /** 461 * An error code that can be reported by {@link #onError} 462 * indicating that the camera device could not be opened 463 * because there are too many other open camera devices. 464 * 465 * <p> 466 * The system-wide limit for number of open cameras has been reached, 467 * and more camera devices cannot be opened until previous instances are 468 * closed. 469 * </p> 470 * 471 * <p> 472 * This error can be produced when opening the camera fails. 473 * </p> 474 * 475 * @see #onError 476 */ 477 public static final int ERROR_MAX_CAMERAS_IN_USE = 2; 478 479 /** 480 * An error code that can be reported by {@link #onError} 481 * indicating that the camera device could not be opened due to a device 482 * policy. 483 * 484 * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) 485 * @see #onError 486 */ 487 public static final int ERROR_CAMERA_DISABLED = 3; 488 489 /** 490 * An error code that can be reported by {@link #onError} 491 * indicating that the camera device has encountered a fatal error. 492 * 493 * <p>The camera device needs to be re-opened to be used again.</p> 494 * 495 * @see #onError 496 */ 497 public static final int ERROR_CAMERA_DEVICE = 4; 498 499 /** 500 * An error code that can be reported by {@link #onError} 501 * indicating that the camera service has encountered a fatal error. 502 * 503 * <p>The Android device may need to be shut down and restarted to restore 504 * camera function, or there may be a persistent hardware problem.</p> 505 * 506 * <p>An attempt at recovery <i>may</i> be possible by closing the 507 * CameraDevice and the CameraManager, and trying to acquire all resources 508 * again from scratch.</p> 509 * 510 * @see #onError 511 */ 512 public static final int ERROR_CAMERA_SERVICE = 5; 513 514 /** 515 * The method called when a camera device has finished opening. 516 * 517 * <p>At this point, the camera device is ready to use, and 518 * {@link CameraDevice#createCaptureSession} can be called to set up the first capture 519 * session.</p> 520 * 521 * @param camera the camera device that has become opened 522 */ onOpened(CameraDevice camera)523 public abstract void onOpened(CameraDevice camera); // Must implement 524 525 /** 526 * The method called when a camera device has been closed with 527 * {@link CameraDevice#close}. 528 * 529 * <p>Any attempt to call methods on this CameraDevice in the 530 * future will throw a {@link IllegalStateException}.</p> 531 * 532 * <p>The default implementation of this method does nothing.</p> 533 * 534 * @param camera the camera device that has become closed 535 */ onClosed(CameraDevice camera)536 public void onClosed(CameraDevice camera) { 537 // Default empty implementation 538 } 539 540 /** 541 * The method called when a camera device is no longer available for 542 * use. 543 * 544 * <p>This callback may be called instead of {@link #onOpened} 545 * if opening the camera fails.</p> 546 * 547 * <p>Any attempt to call methods on this CameraDevice will throw a 548 * {@link CameraAccessException}. The disconnection could be due to a 549 * change in security policy or permissions; the physical disconnection 550 * of a removable camera device; or the camera being needed for a 551 * higher-priority use case.</p> 552 * 553 * <p>There may still be capture callbacks that are invoked 554 * after this method is called, or new image buffers that are delivered 555 * to active outputs.</p> 556 * 557 * <p>The default implementation logs a notice to the system log 558 * about the disconnection.</p> 559 * 560 * <p>You should clean up the camera with {@link CameraDevice#close} after 561 * this happens, as it is not recoverable until opening the camera again 562 * after it becomes {@link CameraManager.AvailabilityCallback#onCameraAvailable available}. 563 * </p> 564 * 565 * @param camera the device that has been disconnected 566 */ onDisconnected(CameraDevice camera)567 public abstract void onDisconnected(CameraDevice camera); // Must implement 568 569 /** 570 * The method called when a camera device has encountered a serious error. 571 * 572 * <p>This callback may be called instead of {@link #onOpened} 573 * if opening the camera fails.</p> 574 * 575 * <p>This indicates a failure of the camera device or camera service in 576 * some way. Any attempt to call methods on this CameraDevice in the 577 * future will throw a {@link CameraAccessException} with the 578 * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason. 579 * </p> 580 * 581 * <p>There may still be capture completion or camera stream callbacks 582 * that will be called after this error is received.</p> 583 * 584 * <p>You should clean up the camera with {@link CameraDevice#close} after 585 * this happens. Further attempts at recovery are error-code specific.</p> 586 * 587 * @param camera The device reporting the error 588 * @param error The error code, one of the 589 * {@code StateCallback.ERROR_*} values. 590 * 591 * @see #ERROR_CAMERA_DEVICE 592 * @see #ERROR_CAMERA_SERVICE 593 * @see #ERROR_CAMERA_DISABLED 594 * @see #ERROR_CAMERA_IN_USE 595 */ onError(CameraDevice camera, int error)596 public abstract void onError(CameraDevice camera, int error); // Must implement 597 } 598 599 /** 600 * Temporary for migrating to Callback naming 601 * @hide 602 */ 603 public static abstract class StateListener extends StateCallback { 604 } 605 606 /** 607 * To be inherited by android.hardware.camera2.* code only. 608 * @hide 609 */ CameraDevice()610 public CameraDevice() {} 611 } 612