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