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