1 /* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.camera2; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.annotation.SystemApi; 23 import android.hardware.camera2.params.ExtensionSessionConfiguration; 24 import android.hardware.camera2.params.InputConfiguration; 25 import android.hardware.camera2.params.OutputConfiguration; 26 import android.hardware.camera2.params.SessionConfiguration; 27 import android.hardware.camera2.params.StreamConfigurationMap; 28 import android.os.Handler; 29 import android.view.Surface; 30 31 import java.lang.annotation.Retention; 32 import java.lang.annotation.RetentionPolicy; 33 import java.util.List; 34 import java.util.Set; 35 36 /** 37 * <p>The CameraDevice class is a representation of a single camera connected to an 38 * Android device, allowing for fine-grain control of image capture and 39 * post-processing at high frame rates.</p> 40 * 41 * <p>Your application must declare the 42 * {@link android.Manifest.permission#CAMERA Camera} permission in its manifest 43 * in order to access camera devices.</p> 44 * 45 * <p>A given camera device may provide support at one of several levels defined 46 * in {@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}. 47 * If a device supports {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} level, 48 * the camera device is running in backward compatibility mode and has minimum camera2 API support. 49 * If a device supports the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} 50 * level, then Camera2 exposes a feature set that is roughly equivalent to the older 51 * {@link android.hardware.Camera Camera} API, although with a cleaner and more 52 * efficient interface. 53 * If a device supports the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL EXTERNAL} 54 * level, then the device is a removable camera that provides similar but slightly less features 55 * as the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} level. 56 * Devices that implement the {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} or 57 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL3} level of support 58 * provide substantially improved capabilities over the older camera 59 * API. If your application requires a full-level device for 60 * proper operation, declare the "android.hardware.camera.level.full" feature in your 61 * manifest.</p> 62 * 63 * @see CameraManager#openCamera 64 * @see android.Manifest.permission#CAMERA 65 * @see CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL 66 */ 67 public abstract class CameraDevice implements AutoCloseable { 68 69 /** 70 * Create a request suitable for a camera preview window. Specifically, this 71 * means that high frame rate is given priority over the highest-quality 72 * post-processing. These requests would normally be used with the 73 * {@link CameraCaptureSession#setRepeatingRequest} method. 74 * This template is guaranteed to be supported on all camera devices. 75 * 76 * @see #createCaptureRequest 77 */ 78 public static final int TEMPLATE_PREVIEW = 1; 79 80 /** 81 * Create a request suitable for still image capture. Specifically, this 82 * means prioritizing image quality over frame rate. These requests would 83 * commonly be used with the {@link CameraCaptureSession#capture} method. 84 * This template is guaranteed to be supported on all camera devices except 85 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_DEPTH_OUTPUT DEPTH_OUTPUT} devices 86 * that are not {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE 87 * BACKWARD_COMPATIBLE}. 88 * @see #createCaptureRequest 89 */ 90 public static final int TEMPLATE_STILL_CAPTURE = 2; 91 92 /** 93 * Create a request suitable for video recording. Specifically, this means 94 * that a stable frame rate is used, and post-processing is set for 95 * recording quality. These requests would commonly be used with the 96 * {@link CameraCaptureSession#setRepeatingRequest} method. 97 * This template is guaranteed to be supported on all camera devices except 98 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_DEPTH_OUTPUT DEPTH_OUTPUT} devices 99 * that are not {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE 100 * BACKWARD_COMPATIBLE}. 101 * 102 * @see #createCaptureRequest 103 */ 104 public static final int TEMPLATE_RECORD = 3; 105 106 /** 107 * Create a request suitable for still image capture while recording 108 * video. Specifically, this means maximizing image quality without 109 * disrupting the ongoing recording. These requests would commonly be used 110 * with the {@link CameraCaptureSession#capture} method while a request based on 111 * {@link #TEMPLATE_RECORD} is is in use with {@link CameraCaptureSession#setRepeatingRequest}. 112 * This template is guaranteed to be supported on all camera devices except 113 * legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 114 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) and 115 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_DEPTH_OUTPUT DEPTH_OUTPUT} devices 116 * that are not {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE 117 * BACKWARD_COMPATIBLE}. 118 * 119 * @see #createCaptureRequest 120 */ 121 public static final int TEMPLATE_VIDEO_SNAPSHOT = 4; 122 123 /** 124 * Create a request suitable for zero shutter lag still capture. This means 125 * means maximizing image quality without compromising preview frame rate. 126 * AE/AWB/AF should be on auto mode. This is intended for application-operated ZSL. For 127 * device-operated ZSL, use {@link CaptureRequest#CONTROL_ENABLE_ZSL} if available. 128 * This template is guaranteed to be supported on camera devices that support the 129 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_PRIVATE_REPROCESSING PRIVATE_REPROCESSING} 130 * capability or the 131 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_YUV_REPROCESSING YUV_REPROCESSING} 132 * capability. 133 * 134 * @see #createCaptureRequest 135 * @see CaptureRequest#CONTROL_ENABLE_ZSL 136 */ 137 public static final int TEMPLATE_ZERO_SHUTTER_LAG = 5; 138 139 /** 140 * A basic template for direct application control of capture 141 * parameters. All automatic control is disabled (auto-exposure, auto-white 142 * balance, auto-focus), and post-processing parameters are set to preview 143 * quality. The manual capture parameters (exposure, sensitivity, and so on) 144 * are set to reasonable defaults, but should be overriden by the 145 * application depending on the intended use case. 146 * This template is guaranteed to be supported on camera devices that support the 147 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR MANUAL_SENSOR} 148 * capability. 149 * 150 * @see #createCaptureRequest 151 */ 152 public static final int TEMPLATE_MANUAL = 6; 153 154 /** @hide */ 155 @Retention(RetentionPolicy.SOURCE) 156 @IntDef(prefix = {"TEMPLATE_"}, value = 157 {TEMPLATE_PREVIEW, 158 TEMPLATE_STILL_CAPTURE, 159 TEMPLATE_RECORD, 160 TEMPLATE_VIDEO_SNAPSHOT, 161 TEMPLATE_ZERO_SHUTTER_LAG, 162 TEMPLATE_MANUAL}) 163 public @interface RequestTemplate {}; 164 165 /** 166 * No vibration or sound muting for this camera device. This is the default 167 * mode for all camera devices. 168 * 169 * @see #setCameraAudioRestriction 170 */ 171 public static final int AUDIO_RESTRICTION_NONE = 0; 172 173 /** 174 * Mute vibration from ringtones, alarms or notifications while this camera device is in use. 175 * 176 * @see #setCameraAudioRestriction 177 */ 178 public static final int AUDIO_RESTRICTION_VIBRATION = 1; 179 180 /** 181 * Mute vibration and sound from ringtones, alarms or notifications while this camera device is 182 * in use. 183 * 184 * @see #setCameraAudioRestriction 185 */ 186 public static final int AUDIO_RESTRICTION_VIBRATION_SOUND = 3; 187 188 /** @hide */ 189 @Retention(RetentionPolicy.SOURCE) 190 @IntDef(prefix = {"AUDIO_RESTRICTION_"}, value = 191 {AUDIO_RESTRICTION_NONE, 192 AUDIO_RESTRICTION_VIBRATION, 193 AUDIO_RESTRICTION_VIBRATION_SOUND}) 194 public @interface CAMERA_AUDIO_RESTRICTION {}; 195 196 /** 197 * Get the ID of this camera device. 198 * 199 * <p>This matches the ID given to {@link CameraManager#openCamera} to instantiate this 200 * this camera device.</p> 201 * 202 * <p>This ID can be used to query the camera device's {@link 203 * CameraCharacteristics fixed properties} with {@link 204 * CameraManager#getCameraCharacteristics}.</p> 205 * 206 * <p>This method can be called even if the device has been closed or has encountered 207 * a serious error.</p> 208 * 209 * @return the ID for this camera device 210 * 211 * @see CameraManager#getCameraCharacteristics 212 * @see CameraManager#getCameraIdList 213 */ 214 @NonNull getId()215 public abstract String getId(); 216 217 /** 218 * <p>Create a new camera capture session by providing the target output set of Surfaces to the 219 * camera device.</p> 220 * 221 * @param outputs The new set of Surfaces that should be made available as 222 * targets for captured image data. 223 * @param callback The callback to notify about the status of the new capture session. 224 * @param handler The handler on which the callback should be invoked, or {@code null} to use 225 * the current thread's {@link android.os.Looper looper}. 226 * 227 * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements, 228 * the callback is null, or the handler is null but the current 229 * thread has no looper. 230 * @throws CameraAccessException if the camera device is no longer connected or has 231 * encountered a fatal error 232 * @throws IllegalStateException if the camera device has been closed 233 * 234 * @see CameraCaptureSession 235 * @see StreamConfigurationMap#getOutputFormats() 236 * @see StreamConfigurationMap#getOutputSizes(int) 237 * @see StreamConfigurationMap#getOutputSizes(Class) 238 * @deprecated Please use {@link 239 * #createCaptureSession(android.hardware.camera2.params.SessionConfiguration)} for the 240 * full set of configuration options available. 241 */ 242 @Deprecated createCaptureSession(@onNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)243 public abstract void createCaptureSession(@NonNull List<Surface> outputs, 244 @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler) 245 throws CameraAccessException; 246 247 /** 248 * <p>Create a new camera capture session by providing the target output set of Surfaces and 249 * its corresponding surface configuration to the camera device.</p> 250 * 251 * @see #createCaptureSession 252 * @see OutputConfiguration 253 * @deprecated Please use {@link 254 * #createCaptureSession(android.hardware.camera2.params.SessionConfiguration)} for the 255 * full set of configuration options available. 256 */ 257 @Deprecated createCaptureSessionByOutputConfigurations( List<OutputConfiguration> outputConfigurations, CameraCaptureSession.StateCallback callback, @Nullable Handler handler)258 public abstract void createCaptureSessionByOutputConfigurations( 259 List<OutputConfiguration> outputConfigurations, 260 CameraCaptureSession.StateCallback callback, @Nullable Handler handler) 261 throws CameraAccessException; 262 /** 263 * Create a new reprocessable camera capture session by providing the desired reprocessing 264 * input Surface configuration and the target output set of Surfaces to the camera device. 265 * 266 * @param inputConfig The configuration for the input {@link Surface} 267 * @param outputs The new set of Surfaces that should be made available as 268 * targets for captured image data. 269 * @param callback The callback to notify about the status of the new capture session. 270 * @param handler The handler on which the callback should be invoked, or {@code null} to use 271 * the current thread's {@link android.os.Looper looper}. 272 * 273 * @throws IllegalArgumentException if the input configuration is null or not supported, the set 274 * of output Surfaces do not meet the requirements, the 275 * callback is null, or the handler is null but the current 276 * thread has no looper. 277 * @throws CameraAccessException if the camera device is no longer connected or has 278 * encountered a fatal error 279 * @throws IllegalStateException if the camera device has been closed 280 * 281 * @see #createCaptureSession 282 * @see CameraCaptureSession 283 * @see StreamConfigurationMap#getInputFormats 284 * @see StreamConfigurationMap#getInputSizes 285 * @see StreamConfigurationMap#getValidOutputFormatsForInput 286 * @see StreamConfigurationMap#getOutputSizes 287 * @see android.media.ImageWriter 288 * @see android.media.ImageReader 289 * @deprecated Please use {@link 290 * #createCaptureSession(android.hardware.camera2.params.SessionConfiguration)} for the 291 * full set of configuration options available. 292 */ 293 @Deprecated createReprocessableCaptureSession(@onNull InputConfiguration inputConfig, @NonNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)294 public abstract void createReprocessableCaptureSession(@NonNull InputConfiguration inputConfig, 295 @NonNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback, 296 @Nullable Handler handler) 297 throws CameraAccessException; 298 299 /** 300 * Create a new reprocessable camera capture session by providing the desired reprocessing 301 * input configuration and output {@link OutputConfiguration} 302 * to the camera device. 303 * 304 * @see #createReprocessableCaptureSession 305 * @see OutputConfiguration 306 * @deprecated Please use {@link 307 * #createCaptureSession(android.hardware.camera2.params.SessionConfiguration)} for the 308 * full set of configuration options available. 309 */ 310 @Deprecated createReprocessableCaptureSessionByConfigurations( @onNull InputConfiguration inputConfig, @NonNull List<OutputConfiguration> outputs, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)311 public abstract void createReprocessableCaptureSessionByConfigurations( 312 @NonNull InputConfiguration inputConfig, 313 @NonNull List<OutputConfiguration> outputs, 314 @NonNull CameraCaptureSession.StateCallback callback, 315 @Nullable Handler handler) 316 throws CameraAccessException; 317 318 /** 319 * <p>Create a new constrained high speed capture session.</p> 320 * 321 * @param outputs The new set of Surfaces that should be made available as 322 * targets for captured high speed image data. 323 * @param callback The callback to notify about the status of the new capture session. 324 * @param handler The handler on which the callback should be invoked, or {@code null} to use 325 * the current thread's {@link android.os.Looper looper}. 326 * 327 * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements, 328 * the callback is null, or the handler is null but the current 329 * thread has no looper, or the camera device doesn't support 330 * high speed video capability. 331 * @throws CameraAccessException if the camera device is no longer connected or has 332 * encountered a fatal error 333 * @throws IllegalStateException if the camera device has been closed 334 * 335 * @see #createCaptureSession 336 * @see CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE 337 * @see StreamConfigurationMap#getHighSpeedVideoSizes 338 * @see StreamConfigurationMap#getHighSpeedVideoFpsRangesFor 339 * @see CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES 340 * @see CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO 341 * @see CameraCaptureSession#captureBurst 342 * @see CameraCaptureSession#setRepeatingBurst 343 * @see CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList 344 * @deprecated Please use {@link 345 * #createCaptureSession(android.hardware.camera2.params.SessionConfiguration)} for the 346 * full set of configuration options available. 347 */ 348 @Deprecated createConstrainedHighSpeedCaptureSession(@onNull List<Surface> outputs, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)349 public abstract void createConstrainedHighSpeedCaptureSession(@NonNull List<Surface> outputs, 350 @NonNull CameraCaptureSession.StateCallback callback, 351 @Nullable Handler handler) 352 throws CameraAccessException; 353 354 /** 355 * Initialize a specific device-specific extension augmented camera capture 356 * session. 357 * 358 * <p>Extension sessions can be used to enable device-specific operation modes like 359 * {@link CameraExtensionCharacteristics#EXTENSION_NIGHT} or 360 * {@link CameraExtensionCharacteristics#EXTENSION_HDR}. These modes are less flexible than the 361 * full camera API, but enable access to more sophisticated processing algorithms that can 362 * capture multi-frame bursts to generate single output images. To query for available 363 * extensions on this device call 364 * {@link CameraExtensionCharacteristics#getSupportedExtensions()}.</p> 365 * 366 * <p>This method will also trigger the setup of the internal 367 * processing pipeline for extension augmented preview and multi-frame 368 * still capture.</p> 369 * 370 * <p>If a prior CameraCaptureSession already exists when this method is called, the previous 371 * session will no longer be able to accept new capture requests and will be closed. Any 372 * in-progress capture requests made on the prior session will be completed before it's closed. 373 * </p> 374 * 375 * <p>The CameraExtensionSession will be active until the client 376 * either calls CameraExtensionSession.close() or creates a new camera 377 * capture session. In both cases all internal resources will be 378 * released, continuous repeating requests stopped and any pending 379 * multi-frame capture requests flushed.</p> 380 * 381 * <p>Note that the CameraExtensionSession currently supports at most wo 382 * multi frame capture surface formats: ImageFormat.JPEG will be supported 383 * by all extensions and ImageFormat.YUV_420_888 may or may not be supported. 384 * Clients must query the multi-frame capture format support using 385 * {@link CameraExtensionCharacteristics#getExtensionSupportedSizes(int, int)}. 386 * For repeating requests CameraExtensionSession supports only 387 * {@link android.graphics.SurfaceTexture} as output. Clients can query the supported resolution 388 * for the repeating request output using 389 * {@link CameraExtensionCharacteristics#getExtensionSupportedSizes(int, Class) 390 * getExtensionSupportedSizes(..., Class)}.</p> 391 * 392 * <p>At the very minimum the initialization expects either one valid output 393 * surface for repeating or one valid output for high-quality single requests registered in the 394 * outputs argument of the extension configuration argument. At the maximum the initialization 395 * will accept two valid output surfaces, one for repeating and the other for single requests. 396 * Additional unsupported surfaces passed to ExtensionSessionConfiguration will cause an 397 * {@link IllegalArgumentException} to be thrown.</p> 398 * 399 * @param extensionConfiguration extension configuration 400 * @throws IllegalArgumentException If both the preview and still 401 * capture surfaces are not set or invalid, or if any of the 402 * registered surfaces do not meet the device-specific 403 * extension requirements such as dimensions and/or 404 * (output format)/(surface type), or if the extension is not 405 * supported, or if any of the output configurations select 406 * a dynamic range different from 407 * {@link android.hardware.camera2.params.DynamicRangeProfiles#STANDARD}, 408 * or if any of the output configurations sets a stream use 409 * case different from {@link 410 * android.hardware.camera2.CameraCharacteristics#SCALER_AVAILABLE_STREAM_USE_CASES_DEFAULT}. 411 * @see CameraExtensionCharacteristics#getSupportedExtensions 412 * @see CameraExtensionCharacteristics#getExtensionSupportedSizes 413 */ createExtensionSession( @onNull ExtensionSessionConfiguration extensionConfiguration)414 public void createExtensionSession( 415 @NonNull ExtensionSessionConfiguration extensionConfiguration) 416 throws CameraAccessException { 417 throw new UnsupportedOperationException("No default implementation"); 418 } 419 420 /** 421 * Standard camera operation mode. 422 * 423 * @see #createCustomCaptureSession 424 * @hide 425 */ 426 @SystemApi 427 public static final int SESSION_OPERATION_MODE_NORMAL = 428 0; // ICameraDeviceUser.NORMAL_MODE; 429 430 /** 431 * Constrained high-speed operation mode. 432 * 433 * @see #createCustomCaptureSession 434 * @hide 435 */ 436 @SystemApi 437 public static final int SESSION_OPERATION_MODE_CONSTRAINED_HIGH_SPEED = 438 1; // ICameraDeviceUser.CONSTRAINED_HIGH_SPEED_MODE; 439 440 /** 441 * First vendor-specific operating mode 442 * 443 * @see #createCustomCaptureSession 444 * @hide 445 */ 446 @SystemApi 447 public static final int SESSION_OPERATION_MODE_VENDOR_START = 448 0x8000; // ICameraDeviceUser.VENDOR_MODE_START; 449 450 /** @hide */ 451 @Retention(RetentionPolicy.SOURCE) 452 @IntDef(prefix = {"SESSION_OPERATION_MODE"}, value = 453 {SESSION_OPERATION_MODE_NORMAL, 454 SESSION_OPERATION_MODE_CONSTRAINED_HIGH_SPEED, 455 SESSION_OPERATION_MODE_VENDOR_START}) 456 public @interface SessionOperatingMode {}; 457 458 /** 459 * Create a new camera capture session with a custom operating mode. 460 * 461 * @param inputConfig The configuration for the input {@link Surface} if a reprocessing session 462 * is desired, or {@code null} otherwise. 463 * @param outputs The new set of {@link OutputConfiguration OutputConfigurations} that should be 464 * made available as targets for captured image data. 465 * @param operatingMode The custom operating mode to use; a nonnegative value, either a custom 466 * vendor value or one of the SESSION_OPERATION_MODE_* values. 467 * @param callback The callback to notify about the status of the new capture session. 468 * @param handler The handler on which the callback should be invoked, or {@code null} to use 469 * the current thread's {@link android.os.Looper looper}. 470 * 471 * @throws IllegalArgumentException if the input configuration is null or not supported, the set 472 * of output Surfaces do not meet the requirements, the 473 * callback is null, or the handler is null but the current 474 * thread has no looper. 475 * @throws CameraAccessException if the camera device is no longer connected or has 476 * encountered a fatal error 477 * @throws IllegalStateException if the camera device has been closed 478 * 479 * @see #createCaptureSession 480 * @see #createReprocessableCaptureSession 481 * @see CameraCaptureSession 482 * @see OutputConfiguration 483 * @deprecated Please use {@link 484 * #createCaptureSession(android.hardware.camera2.params.SessionConfiguration)} for the 485 * full set of configuration options available. 486 * @hide 487 */ 488 @SystemApi 489 @Deprecated createCustomCaptureSession( InputConfiguration inputConfig, @NonNull List<OutputConfiguration> outputs, @SessionOperatingMode int operatingMode, @NonNull CameraCaptureSession.StateCallback callback, @Nullable Handler handler)490 public abstract void createCustomCaptureSession( 491 InputConfiguration inputConfig, 492 @NonNull List<OutputConfiguration> outputs, 493 @SessionOperatingMode int operatingMode, 494 @NonNull CameraCaptureSession.StateCallback callback, 495 @Nullable Handler handler) 496 throws CameraAccessException; 497 498 /** 499 * <p>Create a new {@link CameraCaptureSession} using a {@link SessionConfiguration} helper 500 * object that aggregates all supported parameters.</p> 501 * <p>The active capture session determines the set of potential output Surfaces for 502 * the camera device for each capture request. A given request may use all 503 * or only some of the outputs. Once the CameraCaptureSession is created, requests can be 504 * submitted with {@link CameraCaptureSession#capture capture}, 505 * {@link CameraCaptureSession#captureBurst captureBurst}, 506 * {@link CameraCaptureSession#setRepeatingRequest setRepeatingRequest}, or 507 * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}.</p> 508 * 509 * <p>Surfaces suitable for inclusion as a camera output can be created for 510 * various use cases and targets:</p> 511 * 512 * <ul> 513 * 514 * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Once the SurfaceView's 515 * Surface is {@link android.view.SurfaceHolder.Callback#surfaceCreated created}, set the size 516 * of the Surface with {@link android.view.SurfaceHolder#setFixedSize} to be one of the sizes 517 * returned by {@link StreamConfigurationMap#getOutputSizes(Class) 518 * getOutputSizes(SurfaceHolder.class)} and then obtain the Surface by calling {@link 519 * android.view.SurfaceHolder#getSurface}. If the size is not set by the application, it will 520 * be rounded to the nearest supported size less than 1080p, by the camera device.</li> 521 * 522 * <li>For accessing through an OpenGL texture via a {@link android.graphics.SurfaceTexture 523 * SurfaceTexture}: Set the size of the SurfaceTexture with {@link 524 * android.graphics.SurfaceTexture#setDefaultBufferSize} to be one of the sizes returned by 525 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(SurfaceTexture.class)} 526 * before creating a Surface from the SurfaceTexture with {@link Surface#Surface}. If the size 527 * is not set by the application, it will be set to be the smallest supported size less than 528 * 1080p, by the camera device.</li> 529 * 530 * <li>For recording with {@link android.media.MediaCodec}: Call 531 * {@link android.media.MediaCodec#createInputSurface} after configuring 532 * the media codec to use one of the sizes returned by 533 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaCodec.class)} 534 * </li> 535 * 536 * <li>For recording with {@link android.media.MediaRecorder}: Call 537 * {@link android.media.MediaRecorder#getSurface} after configuring the media recorder to use 538 * one of the sizes returned by 539 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaRecorder.class)}, 540 * or configuring it to use one of the supported 541 * {@link android.media.CamcorderProfile CamcorderProfiles}.</li> 542 * 543 * <li>For efficient YUV processing with {@link android.renderscript}: 544 * Create a RenderScript 545 * {@link android.renderscript.Allocation Allocation} with a supported YUV 546 * type, the IO_INPUT flag, and one of the sizes returned by 547 * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(Allocation.class)}, 548 * Then obtain the Surface with 549 * {@link android.renderscript.Allocation#getSurface}.</li> 550 * 551 * <li>For access to RAW, uncompressed YUV, or compressed JPEG data in the application: Create an 552 * {@link android.media.ImageReader} object with one of the supported output formats given by 553 * {@link StreamConfigurationMap#getOutputFormats()}, setting its size to one of the 554 * corresponding supported sizes by passing the chosen output format into 555 * {@link StreamConfigurationMap#getOutputSizes(int)}. Then obtain a 556 * {@link android.view.Surface} from it with {@link android.media.ImageReader#getSurface()}. 557 * If the ImageReader size is not set to a supported size, it will be rounded to a supported 558 * size less than 1080p by the camera device. 559 * </li> 560 * 561 * </ul> 562 * 563 * <p>The camera device will query each Surface's size and formats upon this 564 * call, so they must be set to a valid setting at this time.</p> 565 * 566 * <p>It can take several hundred milliseconds for the session's configuration to complete, 567 * since camera hardware may need to be powered on or reconfigured. Once the configuration is 568 * complete and the session is ready to actually capture data, the provided 569 * {@link CameraCaptureSession.StateCallback}'s 570 * {@link CameraCaptureSession.StateCallback#onConfigured} callback will be called.</p> 571 * 572 * <p>If a prior CameraCaptureSession already exists when this method is called, the previous 573 * session will no longer be able to accept new capture requests and will be closed. Any 574 * in-progress capture requests made on the prior session will be completed before it's closed. 575 * {@link CameraCaptureSession.StateCallback#onConfigured} for the new session may be invoked 576 * before {@link CameraCaptureSession.StateCallback#onClosed} is invoked for the prior 577 * session. Once the new session is {@link CameraCaptureSession.StateCallback#onConfigured 578 * configured}, it is able to start capturing its own requests. To minimize the transition time, 579 * the {@link CameraCaptureSession#abortCaptures} call can be used to discard the remaining 580 * requests for the prior capture session before a new one is created. Note that once the new 581 * session is created, the old one can no longer have its captures aborted.</p> 582 * 583 * <p>Using larger resolution outputs, or more outputs, can result in slower 584 * output rate from the device.</p> 585 * 586 * <p>Configuring a session with an empty or null list will close the current session, if 587 * any. This can be used to release the current session's target surfaces for another use.</p> 588 * 589 * <h3>Regular capture</h3> 590 * 591 * <p>While any of the sizes from {@link StreamConfigurationMap#getOutputSizes} can be used when 592 * a single output stream is configured, a given camera device may not be able to support all 593 * combination of sizes, formats, and targets when multiple outputs are configured at once. The 594 * tables below list the maximum guaranteed resolutions for combinations of streams and targets, 595 * given the capabilities of the camera device. These are valid for when the 596 * {@link android.hardware.camera2.params.SessionConfiguration#setInputConfiguration 597 * input configuration} is not set and therefore no reprocessing is active.</p> 598 * 599 * <p>If an application tries to create a session using a set of targets that exceed the limits 600 * described in the below tables, one of three possibilities may occur. First, the session may 601 * be successfully created and work normally. Second, the session may be successfully created, 602 * but the camera device won't meet the frame rate guarantees as described in 603 * {@link StreamConfigurationMap#getOutputMinFrameDuration}. Or third, if the output set 604 * cannot be used at all, session creation will fail entirely, with 605 * {@link CameraCaptureSession.StateCallback#onConfigureFailed} being invoked.</p> 606 * 607 * <p>For the type column, {@code PRIV} refers to any target whose available sizes are found 608 * using {@link StreamConfigurationMap#getOutputSizes(Class)} with no direct application-visible 609 * format, {@code YUV} refers to a target Surface using the 610 * {@link android.graphics.ImageFormat#YUV_420_888} format, {@code JPEG} refers to the 611 * {@link android.graphics.ImageFormat#JPEG} format, and {@code RAW} refers to the 612 * {@link android.graphics.ImageFormat#RAW_SENSOR} format.</p> 613 * 614 * <p>For the maximum size column, {@code PREVIEW} refers to the best size match to the 615 * device's screen resolution, or to 1080p ({@code 1920x1080}), whichever is 616 * smaller. {@code RECORD} refers to the camera device's maximum supported recording resolution, 617 * as determined by {@link android.media.CamcorderProfile}. And {@code MAXIMUM} refers to the 618 * camera device's maximum output resolution for that format or target from 619 * {@link StreamConfigurationMap#getOutputSizes}.</p> 620 * 621 * <p>To use these tables, determine the number and the formats/targets of outputs needed, and 622 * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes 623 * that can be used; it is guaranteed that for those targets, the listed sizes and anything 624 * smaller from the list given by {@link StreamConfigurationMap#getOutputSizes} can be 625 * successfully used to create a session. For example, if a row indicates that a 8 megapixel 626 * (MP) YUV_420_888 output can be used together with a 2 MP {@code PRIV} output, then a session 627 * can be created with targets {@code [8 MP YUV, 2 MP PRIV]} or targets {@code [2 MP YUV, 2 MP 628 * PRIV]}; but a session with targets {@code [8 MP YUV, 4 MP PRIV]}, targets {@code [4 MP YUV, 4 629 * MP PRIV]}, or targets {@code [8 MP PRIV, 2 MP YUV]} would not be guaranteed to work, unless 630 * some other row of the table lists such a combination.</p> 631 * 632 * <style scoped> 633 * #rb { border-right-width: thick; } 634 * </style> 635 * <p>Legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 636 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at 637 * least the following stream combinations: 638 * 639 * <table> 640 * <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr> 641 * <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> 642 * <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> 643 * <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> 644 * <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> 645 * <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> 646 * <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> 647 * <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> 648 * <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> 649 * <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> 650 * <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> 651 * </table><br> 652 * </p> 653 * 654 * <p>Limited-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 655 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices 656 * support at least the following stream combinations in addition to those for 657 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: 658 * 659 * <table> 660 * <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr> 661 * <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> 662 * <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> 663 * <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> 664 * <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> 665 * <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> 666 * <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> 667 * <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> 668 * <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> 669 * </table><br> 670 * </p> 671 * 672 * <p>FULL-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 673 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices 674 * support at least the following stream combinations in addition to those for 675 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 676 * 677 * <table> 678 * <tr><th colspan="7">FULL-level additional guaranteed configurations</th></tr> 679 * <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> 680 * <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> 681 * <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> 682 * <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> 683 * <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> 684 * <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> 685 * <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> 686 * <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> 687 * </table><br> 688 * </p> 689 * 690 * <p>RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 691 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support 692 * at least the following stream combinations on both 693 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and 694 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 695 * 696 * <table> 697 * <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr> 698 * <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> 699 * <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> 700 * <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> 701 * <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> 702 * <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> 703 * <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> 704 * <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> 705 * <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> 706 * <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> 707 * <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> 708 * </table><br> 709 * </p> 710 * 711 * <p>BURST-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 712 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices 713 * support at least the below stream combinations in addition to those for 714 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices. Note that all 715 * FULL-level devices support the BURST capability, and the below list is a strict subset of the 716 * list for FULL-level devices, so this table is only relevant for LIMITED-level devices that 717 * support the BURST_CAPTURE capability. 718 * 719 * <table> 720 * <tr><th colspan="5">BURST-capability additional guaranteed configurations</th></tr> 721 * <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> 722 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 723 * <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> 724 * <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> 725 * <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> 726 * </table><br> 727 * </p> 728 * 729 * <p>LEVEL-3 ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 730 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL_3}) 731 * support at least the following stream combinations in addition to the combinations for 732 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and for 733 * RAW capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 734 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}): 735 * 736 * <table> 737 * <tr><th colspan="11">LEVEL-3 additional guaranteed configurations</th></tr> 738 * <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 colspan="2" id="rb">Target 4</th><th rowspan="2">Sample use case(s)</th> </tr> 739 * <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> </tr> 740 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code 640x480}</td> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>In-app viewfinder analysis with dynamic selection of output format.</td> </tr> 741 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code 640x480}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>In-app viewfinder analysis with dynamic selection of output format.</td> </tr> 742 * </table><br> 743 * </p> 744 * 745 *<p>BACKWARD_COMPATIBLE devices capable of streaming concurrently with other devices as described by 746 * {@link android.hardware.camera2.CameraManager#getConcurrentCameraIds} have the 747 * following guaranteed streams (when streaming concurrently with other devices)</p> 748 * <p> Note: The sizes mentioned for these concurrent streams are the maximum sizes guaranteed 749 * to be supported. Sizes smaller than these, obtained by {@link StreamConfigurationMap#getOutputSizes} for a particular format, are supported as well. </p> 750 * 751 * <table> 752 * <tr><th colspan="5">Concurrent stream guaranteed configurations</th></tr> 753 * <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> 754 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 755 * <tr> <td>{@code YUV}</td><td id="rb">{@code s1440p}</td> <td colspan="2" id="rb"></td> <td>In-app video / image processing.</td> </tr> 756 * <tr> <td>{@code PRIV}</td><td id="rb">{@code s1440p}</td> <td colspan="2" id="rb"></td> <td>In-app viewfinder analysis.</td> </tr> 757 * <tr> <td>{@code JPEG}</td><td id="rb">{@code s1440p}</td> <td colspan="2" id="rb"></td> <td>No viewfinder still image capture.</td> </tr> 758 * <tr> <td>{@code YUV / PRIV}</td><td id="rb">{@code s720p}</td> <td>{@code JPEG}</td><td id="rb">{@code s1440p}</td> <td> Standard still imaging.</td> </tr> 759 * <tr> <td>{@code YUV / PRIV}</td><td id="rb">{@code s720p}</td> <td>{@code YUV / PRIV }</td><td id="rb">{@code s1440p}</td> <td>In-app video / processing with preview.</td> </tr> 760 * </table><br> 761 * </p> 762 * 763 * <p> Devices which are not backwards-compatible, support a mandatory single stream of size sVGA with image format {@code DEPTH16} during concurrent operation. </p> 764 * 765 * <p> For guaranteed concurrent stream configurations:</p> 766 * <p> sVGA refers to the camera device's maximum resolution for that format from {@link StreamConfigurationMap#getOutputSizes} or 767 * VGA resolution (640X480) whichever is lower. </p> 768 * <p> s720p refers to the camera device's maximum resolution for that format from {@link StreamConfigurationMap#getOutputSizes} or 769 * 720p(1280X720) whichever is lower. </p> 770 * <p> s1440p refers to the camera device's maximum resolution for that format from {@link StreamConfigurationMap#getOutputSizes} or 771 * 1440p(1920X1440) whichever is lower. </p> 772 * <p>MONOCHROME-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} 773 * includes {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MONOCHROME MONOCHROME}) devices 774 * supporting {@link android.graphics.ImageFormat#Y8 Y8} support substituting {@code YUV} 775 * streams with {@code Y8} in all guaranteed stream combinations for the device's hardware level 776 * and capabilities.</p> 777 * 778 * <p>Clients can access the above mandatory stream combination tables via 779 * {@link android.hardware.camera2.params.MandatoryStreamCombination}.</p> 780 * 781 * <p>Devices capable of outputting HEIC formats ({@link StreamConfigurationMap#getOutputFormats} 782 * contains {@link android.graphics.ImageFormat#HEIC}) will support substituting {@code JPEG} 783 * streams with {@code HEIC} in all guaranteed stream combinations for the device's hardware 784 * level and capabilities. Calling createCaptureSession with both JPEG and HEIC outputs is not 785 * supported.</p> 786 * 787 * <p>Devices capable of multi-resolution output for a particular format ( 788 * {@link android.hardware.camera2.params.MultiResolutionStreamConfigurationMap#getOutputInfo} 789 * returns a non-empty list) support using {@link MultiResolutionImageReader} for MAXIMUM 790 * resolution streams of that format for all mandatory stream combinations. For example, 791 * if a LIMITED camera device supports multi-resolution output streams for both {@code JPEG} and 792 * {@code PRIVATE}, in addition to the stream configurations 793 * in the LIMITED and Legacy table above, the camera device supports the following guaranteed 794 * stream combinations ({@code MULTI_RES} in the Max size column refers to a {@link 795 * MultiResolutionImageReader} created based on the variable max resolutions supported): 796 * 797 * <table> 798 * <tr><th colspan="7">LEGACY-level additional guaranteed combinations with MultiResolutionoutputs</th></tr> 799 * <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> 800 * <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> 801 * <tr> <td>{@code PRIV}</td><td id="rb">{@code MULTI_RES}</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> 802 * <tr> <td>{@code JPEG}</td><td id="rb">{@code MULTI_RES}</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-viewfinder still image capture.</td> </tr> 803 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MULTI_RES}</td> <td colspan="2" id="rb"></td> <td>Standard still imaging.</td> </tr> 804 * <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 MULTI_RES}</td> <td>Still capture plus in-app processing.</td> </tr> 805 * </table><br> 806 * <table> 807 * <tr><th colspan="7">LIMITED-level additional guaranteed configurations with MultiResolutionoutputs</th></tr> 808 * <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> 809 * <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> 810 * <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 MULTI_RES}</td> <td>Two-input in-app processing with still capture.</td> </tr> 811 * </table><br> 812 * The same logic applies to other hardware levels and capabilities. 813 * </p> 814 * 815 * <p> Devices with the ULTRA_HIGH_RESOLUTION_SENSOR capability have some additional guarantees 816 * which clients can take advantage of : </p> 817 * <table> 818 * <tr><th colspan="10">Additional guaranteed combinations for ULTRA_HIGH_RESOLUTION sensors</th></tr> 819 * <tr> <th colspan="3" id="rb">Target 1</th> <th colspan="3" id="rb">Target 2</th> <th colspan="3" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 820 * <tr> <th>Type</th><th id="rb"> SC Map</th><th id="rb">Max size</th> <th>Type</th><th id="rb"> SC Map</th><th id="rb">Max size</th> <th>Type</th><th id="rb"> SC Map</th><th id="rb">Max size</th></tr> 821 * <tr> <td>{@code YUV / JPEG / RAW}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td><td id="rb">{@code PRIV / YUV}</td><td id="rb">{@code DEFAULT}</td><td id="rb">{@code PREVIEW}</td><td colspan="3" id="rb"></td> <td>Ultra high res still image capture with preview</td> </tr> 822 * <tr> <td>{@code YUV / JPEG / RAW}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td><td id="rb">{@code PRIV}</td><td id="rb">{@code DEFAULT}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PRIV / YUV}</td><td id="rb">{@code DEFAULT}</td><td id="rb">{@code RECORD}</td> <td>Ultra high res still capture with preview + app based RECORD size analysis</td> </tr> 823 * <tr> <td>{@code YUV / JPEG / RAW}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td><td id="rb">{@code PRIV}</td><td id="rb">{@code DEFAULT}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code JPEG / YUV / RAW}</td><td id="rb">{@code DEFAULT}</td><td id="rb">{@code MAX}</td> <td>Ultra high res still image capture with preview + default sensor pixel mode analysis stream</td> </tr> 824 * </table><br> 825 * 826 * <p> Here, SC Map, refers to the {@link StreamConfigurationMap}, the target stream sizes must 827 * be chosen from. {@code DEFAULT} refers to the default sensor pixel mode {@link 828 * StreamConfigurationMap} and {@code MAX_RES} refers to the maximum resolution {@link 829 * StreamConfigurationMap}. The same capture request must not mix targets from 830 * {@link StreamConfigurationMap}s corresponding to different sensor pixel modes. </p> 831 * 832 * <p> 10-bit output capable 833 * {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} 834 * devices support at least the following stream combinations: </p> 835 * <table> 836 * <tr><th colspan="7">10-bit output additional guaranteed configurations</th></tr> 837 * <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> 838 * <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> 839 * <tr> <td>{@code PRIV}</td><td id="rb">{@code MAXIMUM}</td> }</td> <td colspan="4" id="rb"></td> <td>Simple preview, GPU video processing, or no-preview video recording.</td> </tr> 840 * <tr> <td>{@code YUV}</td><td id="rb">{@code MAXIMUM}</td> }</td> <td colspan="4" id="rb"></td> <td>In-application video/image processing.</td> </tr> 841 * <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> 842 * <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> 843 * <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 processing.</td> </tr> 844 * <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> 845 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV}</td><td id="rb">{@code RECORD }</td> <td>{@code YUV}</td><td id="rb">{@code RECORD }</td> <td>High-resolution recording with in-app snapshot.</td> </tr> 846 * <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> 847 * </table><br> 848 * <p>Here PRIV can be either 8 or 10-bit {@link android.graphics.ImageFormat#PRIVATE} pixel 849 * format. YUV can be either {@link android.graphics.ImageFormat#YUV_420_888} or 850 * {@link android.graphics.ImageFormat#YCBCR_P010}. 851 * For the maximum size column, PREVIEW refers to the best size match to the device's screen 852 * resolution, or to 1080p (1920x1080), whichever is smaller. RECORD refers to the camera 853 * device's maximum supported recording resolution, as determined by 854 * {@link android.media.CamcorderProfile}. MAXIMUM refers to the camera device's maximum output 855 * resolution for that format or target from {@link StreamConfigurationMap#getOutputSizes(int)}. 856 * Do note that invalid combinations such as having a camera surface configured to use pixel 857 * format {@link android.graphics.ImageFormat#YUV_420_888} with a 10-bit profile 858 * will cause a capture session initialization failure. 859 * </p> 860 * 861 * <p>Devices with the STREAM_USE_CASE capability ({@link 862 * CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes {@link 863 * CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_STREAM_USE_CASE}) support below additional 864 * stream combinations: 865 * 866 * <table> 867 * <tr><th colspan="10">STREAM_USE_CASE capability additional guaranteed configurations</th></tr> 868 * <tr><th colspan="3" id="rb">Target 1</th><th colspan="3" id="rb">Target 2</th><th colspan="3" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 869 * <tr><th>Type</th><th id="rb">Max size</th><th>Usecase</th><th>Type</th><th id="rb">Max size</th><th>Usecase</th><th>Type</th><th id="rb">Max size</th><th>Usecase</th> </tr> 870 * <tr> <td>{@code YUV / PRIV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td colspan="3" id="rb"></td> <td colspan="3" id="rb"></td> <td>Simple preview or in-app image processing</td> </tr> 871 * <tr> <td>{@code YUV / PRIV}</td><td id="rb">{@code RECORD}</td><td id="rb">{@code VIDEO_RECORD}</td> <td colspan="3" id="rb"></td> <td colspan="3" id="rb"></td> <td>Simple video recording or in-app video processing</td> </tr> 872 * <tr> <td>{@code YUV / JPEG}</td><td id="rb">{@code MAXIMUM}</td><td id="rb">{@code STILL_CAPTURE}</td> <td colspan="3" id="rb"></td> <td colspan="3" id="rb"></td> <td>Simple JPEG or YUV still image capture</td> </tr> 873 * <tr> <td>{@code YUV / PRIV}</td><td id="rb">{@code s1440p}</td><td id="rb">{@code PREVIEW_VIDEO_STILL}</td> <td colspan="3" id="rb"></td> <td colspan="3" id="rb"></td> <td>Multi-purpose stream for preview, video and still image capture</td> </tr> 874 * <tr> <td>{@code YUV / PRIV}</td><td id="rb">{@code s1440p}</td><td id="rb">{@code VIDEO_CALL}</td> <td colspan="3" id="rb"></td> <td colspan="3" id="rb"></td> <td>Simple video call</td> </tr> 875 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV / JPEG}</td><td id="rb">{@code MAXIMUM}</td><td id="rb">{@code STILL_CAPTURE}</td> <td colspan="3" id="rb"></td> <td>Preview with JPEG or YUV still image capture</td> </tr> 876 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV / PRIV}</td><td id="rb">{@code RECORD}</td><td id="rb">{@code VIDEO_RECORD}</td> <td colspan="3" id="rb"></td> <td>Preview with video recording or in-app video processing</td> </tr> 877 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td colspan="3" id="rb"></td> <td>Preview with in-application image processing</td> </tr> 878 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV / PRIV}</td><td id="rb">{@code s1440p}</td><td id="rb">{@code VIDEO_CALL}</td> <td colspan="3" id="rb"></td> <td>Preview with video call</td> </tr> 879 * <tr> <td>{@code YUV / PRIV}</td><td id="rb">{@code s1440p}</td><td id="rb">{@code PREVIEW_VIDEO_STILL}</td> <td>{@code YUV / JPEG}</td><td id="rb">{@code MAXIMUM}</td><td id="rb">{@code STILL_CAPTURE}</td> <td colspan="3" id="rb"></td> <td>Multi-purpose stream with JPEG or YUV still capture</td> </tr> 880 * <tr> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code STILL_CAPTURE}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td><td id="rb">{@code STILL_CAPTURE}</td> <td colspan="3" id="rb"></td> <td>YUV and JPEG concurrent still image capture (for testing)</td> </tr> 881 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV / PRIV}</td><td id="rb">{@code RECORD}</td><td id="rb">{@code VIDEO_RECORD}</td> <td>{@code JPEG}</td><td id="rb">{@code RECORD}</td><td id="rb">{@code STILL_CAPTURE}</td> <td>Preview, video record and JPEG video snapshot</td> </tr> 882 * <tr> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td><td id="rb">{@code STILL_CAPTURE}</td> <td>Preview, in-application image processing, and JPEG still image capture</td> </tr> 883 * </table><br> 884 * </p> 885 * 886 *<p> For devices where {@link CameraCharacteristics#CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES} 887 * includes {@link CameraMetadata#CONTROL_VIDEO_STABILIZATION_MODE_PREVIEW_STABILIZATION}, 888 * the following stream combinations are guaranteed, 889 * for CaptureRequests where {@link CaptureRequest#CONTROL_VIDEO_STABILIZATION_MODE} is set to 890 * {@link CameraMetadata#CONTROL_VIDEO_STABILIZATION_MODE_PREVIEW_STABILIZATION} <p> 891 * <table> 892 * <tr><th colspan="7">Preview stabilization guaranteed stream configurations</th></tr> 893 * <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> 894 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 895 * <tr> <td>{@code PRIV / YUV}</td><td id="rb">{@code s1440p}</td><td colspan="2" id="rb"></td> <td>Stabilized preview, GPU video processing, or no-preview stabilized video recording.</td> </tr> 896 * <tr> <td>{@code PRIV / YUV}</td><td id="rb">{@code s1440p}</td> <td>{@code JPEG / YUV}</td><td id="rb">{@code MAXIMUM }</td><td>Standard still imaging with stabilized preview.</td> </tr> 897 * <tr> <td>{@code PRIV / YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code PRIV / YUV}</td><td id="rb">{@code s1440p }</td><td>High-resolution recording with stabilized preview and recording stream.</td> </tr> 898 * </table><br> 899 * <p> 900 * For the maximum size column, PREVIEW refers to the best size match to the device's screen 901 * resolution, or to 1080p (1920x1080), whichever is smaller. RECORD refers to the camera 902 * device's maximum supported recording resolution, as determined by 903 * {@link android.media.CamcorderProfile}. MAXIMUM refers to the camera device's maximum output 904 * resolution for that format or target from {@link StreamConfigurationMap#getOutputSizes(int)}. 905 * </p> 906 * 907 * <p>Since the capabilities of camera devices vary greatly, a given camera device may support 908 * target combinations with sizes outside of these guarantees, but this can only be tested for 909 * by calling {@link #isSessionConfigurationSupported} or attempting to create a session with 910 * such targets.</p> 911 * 912 * <p>Exception on 176x144 (QCIF) resolution: 913 * Camera devices usually have a fixed capability for downscaling from larger resolution to 914 * smaller, and the QCIF resolution sometimes is not fully supported due to this 915 * limitation on devices with high-resolution image sensors. Therefore, trying to configure a 916 * QCIF resolution stream together with any other stream larger than 1920x1080 resolution 917 * (either width or height) might not be supported, and capture session creation will fail if it 918 * is not.</p> 919 * 920 * <h3>Reprocessing</h3> 921 * 922 * <p>If a camera device supports YUV reprocessing 923 * ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_YUV_REPROCESSING}) or PRIVATE 924 * reprocessing 925 * ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_PRIVATE_REPROCESSING}), the 926 * application can also create a reprocessable capture session to submit reprocess capture 927 * requests in addition to regular capture requests, by setting an 928 * {@link android.hardware.camera2.params.SessionConfiguration#setInputConfiguration 929 * input configuration} for the session. A reprocess capture request takes the next available 930 * buffer from the 931 * session's input Surface, and sends it through the camera device's processing pipeline again, 932 * to produce buffers for the request's target output Surfaces. No new image data is captured 933 * for a reprocess request. However the input buffer provided by the application must be 934 * captured previously by the same camera device in the same session directly (e.g. for 935 * Zero-Shutter-Lag use case) or indirectly (e.g. combining multiple output images).</p> 936 * 937 * <p>The active reprocessable capture session determines an input {@link Surface} and the set 938 * of potential output Surfaces for the camera devices for each capture request. The application 939 * can use {@link #createCaptureRequest createCaptureRequest} to create regular capture requests 940 * to capture new images from the camera device, and use {@link #createReprocessCaptureRequest 941 * createReprocessCaptureRequest} to create reprocess capture requests to process buffers from 942 * the input {@link Surface}. Some combinations of output Surfaces in a session may not be used 943 * in a request simultaneously. The guaranteed combinations of output Surfaces that can be used 944 * in a request simultaneously are listed in the tables under {@link #createCaptureSession 945 * createCaptureSession}. All the output Surfaces in one capture request will come from the 946 * same source, either from a new capture by the camera device, or from the input Surface 947 * depending on if the request is a reprocess capture request.</p> 948 * 949 * <p>Input formats and sizes supported by the camera device can be queried via 950 * {@link StreamConfigurationMap#getInputFormats} and 951 * {@link StreamConfigurationMap#getInputSizes}. For each supported input format, the camera 952 * device supports a set of output formats and sizes for reprocessing that can be queried via 953 * {@link StreamConfigurationMap#getValidOutputFormatsForInput} and 954 * {@link StreamConfigurationMap#getOutputSizes}. While output Surfaces with formats that 955 * aren't valid reprocess output targets for the input configuration can be part of a session, 956 * they cannot be used as targets for a reprocessing request.</p> 957 * 958 * <p>Since the application cannot access {@link android.graphics.ImageFormat#PRIVATE} images 959 * directly, an output Surface created by {@link android.media.ImageReader#newInstance} with 960 * {@link android.graphics.ImageFormat#PRIVATE} as the format will be considered as intended to 961 * be used for reprocessing input and thus the {@link android.media.ImageReader} size must 962 * match one of the supported input sizes for {@link android.graphics.ImageFormat#PRIVATE} 963 * format. Otherwise, creating a reprocessable capture session will fail.</p> 964 * 965 * <p>Starting from API level 30, recreating a reprocessable capture session will flush all the 966 * queued but not yet processed buffers from the input surface.</p> 967 * 968 * <p>The configurations in the tables below are guaranteed for creating a reprocessable 969 * capture session if the camera device supports YUV reprocessing or PRIVATE reprocessing. 970 * However, not all output targets used to create a reprocessable session may be used in a 971 * {@link CaptureRequest} simultaneously. For devices that support only 1 output target in a 972 * reprocess {@link CaptureRequest}, submitting a reprocess {@link CaptureRequest} with multiple 973 * output targets will result in a {@link CaptureFailure}. For devices that support multiple 974 * output targets in a reprocess {@link CaptureRequest}, the guaranteed output targets that can 975 * be included in a {@link CaptureRequest} simultaneously are listed in the tables under 976 * {@link #createCaptureSession createCaptureSession}. For example, with a FULL-capability 977 * ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} {@code == } 978 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) device that supports PRIVATE 979 * reprocessing, an application can create a reprocessable capture session with 1 input, 980 * ({@code PRIV}, {@code MAXIMUM}), and 3 outputs, ({@code PRIV}, {@code MAXIMUM}), 981 * ({@code PRIV}, {@code PREVIEW}), and ({@code YUV}, {@code MAXIMUM}). However, it's not 982 * guaranteed that an application can submit a regular or reprocess capture with ({@code PRIV}, 983 * {@code MAXIMUM}) and ({@code YUV}, {@code MAXIMUM}) outputs based on the table listed under 984 * {@link #createCaptureSession createCaptureSession}. In other words, use the tables below to 985 * determine the guaranteed stream configurations for creating a reprocessable capture session, 986 * and use the tables under {@link #createCaptureSession createCaptureSession} to determine the 987 * guaranteed output targets that can be submitted in a regular or reprocess 988 * {@link CaptureRequest} simultaneously.</p> 989 * 990 * <p>Reprocessing with 10-bit output targets on 10-bit capable 991 * {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_DYNAMIC_RANGE_TEN_BIT} devices is 992 * not supported. Trying to initialize a repreocessable capture session with one ore more 993 * output configurations set {@link OutputConfiguration#setDynamicRangeProfile} to use 994 * a 10-bit dynamic range profile {@link android.hardware.camera2.params.DynamicRangeProfiles} 995 * will trigger {@link IllegalArgumentException}.</p> 996 * 997 * <style scoped> 998 * #rb { border-right-width: thick; } 999 * </style> 1000 * 1001 * <p>LIMITED-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 1002 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices 1003 * support at least the following stream combinations for creating a reprocessable capture 1004 * session in addition to those listed earlier for regular captures for 1005 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 1006 * 1007 * <table> 1008 * <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> 1009 * <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> 1010 * <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> 1011 * <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> 1012 * <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> 1013 * <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> 1014 * <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> 1015 * </table><br> 1016 * </p> 1017 * 1018 * <p>FULL-level ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 1019 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices 1020 * support at least the following stream combinations for creating a reprocessable capture 1021 * session in addition to those for 1022 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 1023 * 1024 * <table> 1025 * <tr><th colspan="11">FULL-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> 1026 * <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> 1027 * <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> 1028 * <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> 1029 * <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> 1030 * <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> 1031 * <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> 1032 * <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> 1033 * <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> 1034 * </table><br> 1035 * </p> 1036 * 1037 * <p>RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes 1038 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support 1039 * at least the following stream combinations for creating a reprocessable capture session 1040 * on both {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and 1041 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices 1042 * 1043 * <table> 1044 * <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> 1045 * <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> 1046 * <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> 1047 * <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> 1048 * <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> 1049 * <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> 1050 * <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> 1051 * <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> 1052 * </table><br> 1053 * </p> 1054 * 1055 * <p>LEVEL-3 ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} 1056 * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL_3}) devices 1057 * support at least the following stream combinations for creating a reprocessable capture 1058 * session in addition to those for 1059 * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} devices. Note that while 1060 * the second configuration allows for configuring {@code MAXIMUM} {@code YUV} and {@code JPEG} 1061 * outputs at the same time, that configuration is not listed for regular capture sessions, and 1062 * therefore simultaneous output to both targets is not allowed. 1063 * 1064 * <table> 1065 * <tr><th colspan="13">LEVEL-3 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 always guaranteed.</th></tr> 1066 * <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 colspan="2" id="rb">Target 5</th><th rowspan="2">Sample use case(s)</th> </tr> 1067 * <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><th>Type</th><th id="rb">Max size</th></tr> 1068 * <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>{@code PRIV}</td><td id="rb">{@code 640x480}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td></td><td id="rb"></td> <td>In-app viewfinder analysis with ZSL and RAW.</td> </tr> 1069 * <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 PRIV}</td><td id="rb">{@code 640x480}</td> <td>{@code RAW}</td><td id="rb">{@code MAXIMUM}</td> <td>{@code JPEG}</td><td id="rb">{@code MAXIMUM}</td><td>In-app viewfinder analysis with ZSL, RAW, and JPEG reprocessing output.</td> </tr> 1070 * </table><br> 1071 * </p> 1072 * 1073 * <p>If a camera device supports multi-resolution {@code YUV} input and multi-resolution 1074 * {@code YUV} output or supports multi-resolution {@code PRIVATE} input and multi-resolution 1075 * {@code PRIVATE} output, the additional mandatory stream combinations for LIMITED and FULL devices are listed 1076 * below ({@code MULTI_RES} in the Max size column refers to a 1077 * {@link MultiResolutionImageReader} for output, and a multi-resolution 1078 * {@link InputConfiguration} for input): 1079 * <table> 1080 * <tr><th colspan="11">LIMITED-level additional guaranteed configurations for creating a reprocessable capture session with multi-resolution input and multi-resolution outputs<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> 1081 * <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> 1082 * <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> 1083 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MULTI_RES}</td> <td>Same as input</td><td id="rb">{@code MULTI_RES}</td> <td>{@code JPEG}</td><td id="rb">{@code MULTI_RES}</td> <td></td><td id="rb"></td> <td></td><td id="rb"></td> <td>No-viewfinder still image reprocessing.</td> </tr> 1084 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MULTI_RES}</td> <td>Same as input</td><td id="rb">{@code MULTI_RES}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MULTI_RES}</td> <td></td><td id="rb"></td> <td>ZSL(Zero-Shutter-Lag) still imaging.</td> </tr> 1085 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MULTI_RES}</td> <td>Same as input</td><td id="rb">{@code MULTI_RES}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code JPEG}</td><td id="rb">{@code MULTI_RES}</td> <td></td><td id="rb"></td> <td>ZSL still and in-app processing imaging.</td> </tr> 1086 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MULTI_RES}</td> <td>Same as input</td><td id="rb">{@code MULTI_RES}</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 MULTI_RES}</td> <td>ZSL in-app processing with still capture.</td> </tr> 1087 * </table><br> 1088 * <table> 1089 * <tr><th colspan="11">FULL-level additional guaranteed configurations for creating a reprocessable capture session with multi-resolution input and multi-resolution outputs<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> 1090 * <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> 1091 * <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> 1092 * <tr> <td>{@code PRIV}</td><td id="rb">{@code MULTI_RES}</td> <td>{@code PRIV}</td><td id="rb">{@code MULTI_RES}</td> <td>{@code PRIV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code MULTI_RES}</td> <td></td><td id="rb"></td> <td>Maximum-resolution ZSL in-app processing with regular preview.</td> </tr> 1093 * <tr> <td>{@code PRIV}</td><td id="rb">{@code MULTI_RES}</td> <td>{@code PRIV}</td><td id="rb">{@code MULTI_RES}</td> <td>{@code YUV}</td><td id="rb">{@code PREVIEW}</td> <td>{@code YUV}</td><td id="rb">{@code MULTI_RES}</td> <td></td><td id="rb"></td> <td>Maximum-resolution two-input ZSL in-app processing.</td> </tr> 1094 * <tr> <td>{@code PRIV}/{@code YUV}</td><td id="rb">{@code MULTI_RES}</td> <td>Same as input</td><td id="rb">{@code MULTI_RES}</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 MULTI_RES}</td> <td>ZSL still capture and in-app processing.</td> </tr> 1095 * </table><br> 1096 * <p> Devices with the ULTRA_HIGH_RESOLUTION_SENSOR capability have some additional guarantees 1097 * which clients can take advantage of : </p> 1098 * <table> 1099 * <tr><th colspan="13">Additional guaranteed combinations for ULTRA_HIGH_RESOLUTION sensors (YUV / PRIV inputs are guaranteed only if YUV / PRIVATE reprocessing are supported)</th></tr> 1100 * <tr> <th colspan="3" id="rb">Input</th> <th colspan="3" id="rb">Target 1</th> <th colspan="3" id="rb">Target 2</th> <th colspan="3" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 1101 * <tr> <th>Type</th><th id="rb"> SC Map</th><th id="rb">Max size</th><th>Type</th><th id="rb"> SC Map</th><th id="rb">Max size</th> <th>Type</th><th id="rb"> SC Map</th><th id="rb">Max size</th> <th>Type</th><th id="rb"> SC Map</th><th id="rb">Max size</th></tr> 1102 * <tr> <td>{@code RAW}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td><td>{@code RAW}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td><td id="rb">{@code PRIV / YUV}</td><td id="rb">{@code DEFAULT}</td><td id="rb">{@code PREVIEW}</td><td colspan="3" id="rb"></td> <td>RAW remosaic reprocessing with seperate preview</td> </tr> 1103 * <tr> <td>{@code RAW}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td><td>{@code RAW}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td><td id="rb">{@code PRIV / YUV}</td><td id="rb">{@code DEFAULT}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code JPEG / YUV}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td> <td>Ultra high res RAW -> JPEG / YUV with seperate preview</td> </tr> 1104 * <tr> <td>{@code YUV / PRIV}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td> <td>{@code YUV / PRIV}</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td><td id="rb">{@code YUV / PRIV}</td><td id="rb">{@code DEFAULT}</td><td id="rb">{@code PREVIEW}</td><td id="rb">{@code JPEG }</td><td id="rb">{@code MAX_RES}</td><td id="rb">{@code MAX}</td> <td> Ultra high res PRIV / YUV -> YUV / JPEG reprocessing with seperate preview</td> </tr> 1105 * </table><br> 1106 * No additional mandatory stream combinations for RAW capability and LEVEL-3 hardware level. 1107 * </p> 1108 * 1109 * <h3>Constrained high-speed recording</h3> 1110 * 1111 * <p>The application can use a 1112 * {@link android.hardware.camera2.params.SessionConfiguration#SESSION_REGULAR 1113 * normal capture session} 1114 * for high speed capture if the desired high speed FPS ranges are advertised by 1115 * {@link CameraCharacteristics#CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES}, in which case all API 1116 * semantics associated with normal capture sessions applies.</p> 1117 * 1118 * <p>A 1119 * {@link android.hardware.camera2.params.SessionConfiguration#SESSION_HIGH_SPEED 1120 * high-speed capture session} 1121 * can be use for high speed video recording (>=120fps) when the camera device supports high 1122 * speed video capability (i.e., {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} 1123 * contains {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO}). 1124 * A constrained high-speed capture session has special limitations compared with a normal 1125 * capture session:</p> 1126 * 1127 * <ul> 1128 * 1129 * <li>In addition to the output target Surface requirements specified above for regular 1130 * captures, a high speed capture session will only support up to 2 output Surfaces, though 1131 * the application might choose to configure just one Surface (e.g., preview only). All 1132 * Surfaces must be either video encoder surfaces (acquired by 1133 * {@link android.media.MediaRecorder#getSurface} or 1134 * {@link android.media.MediaCodec#createInputSurface}) or preview surfaces (obtained from 1135 * {@link android.view.SurfaceView}, {@link android.graphics.SurfaceTexture} via 1136 * {@link android.view.Surface#Surface(android.graphics.SurfaceTexture)}). The Surface sizes 1137 * must be one of the sizes reported by {@link StreamConfigurationMap#getHighSpeedVideoSizes}. 1138 * When multiple Surfaces are configured, their size must be same.</li> 1139 * 1140 * <li>An active high speed capture session only accepts request lists created via 1141 * {@link CameraConstrainedHighSpeedCaptureSession#createHighSpeedRequestList}, and the 1142 * request list can only be submitted to this session via 1143 * {@link CameraCaptureSession#captureBurst captureBurst}, or 1144 * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}.</li> 1145 * 1146 * <li>The FPS ranges being requested to this session must be selected from 1147 * {@link StreamConfigurationMap#getHighSpeedVideoFpsRangesFor}. The application can still use 1148 * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE} to control the desired FPS range. 1149 * Switching to an FPS range that has different 1150 * {@link android.util.Range#getUpper() maximum FPS} may trigger some camera device 1151 * reconfigurations, which may introduce extra latency. It is recommended that the 1152 * application avoids unnecessary maximum target FPS changes as much as possible during high 1153 * speed streaming.</li> 1154 * 1155 * <li>For the request lists submitted to this session, the camera device will override the 1156 * {@link CaptureRequest#CONTROL_MODE control mode}, auto-exposure (AE), auto-white balance 1157 * (AWB) and auto-focus (AF) to {@link CameraMetadata#CONTROL_MODE_AUTO}, 1158 * {@link CameraMetadata#CONTROL_AE_MODE_ON}, {@link CameraMetadata#CONTROL_AWB_MODE_AUTO} 1159 * and {@link CameraMetadata#CONTROL_AF_MODE_CONTINUOUS_VIDEO}, respectively. All 1160 * post-processing block mode controls will be overridden to be FAST. Therefore, no manual 1161 * control of capture and post-processing parameters is possible. Beside these, only a subset 1162 * of controls will work, see 1163 * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_CONSTRAINED_HIGH_SPEED_VIDEO} for 1164 * more details.</li> 1165 * 1166 * </ul> 1167 * 1168 * 1169 * @param config A session configuration (see {@link SessionConfiguration}). 1170 * 1171 * @throws IllegalArgumentException In case the session configuration is invalid; or the output 1172 * configurations are empty; or the session configuration 1173 * executor is invalid; 1174 * or the output dynamic range combination is 1175 * invalid/unsupported. 1176 * @throws CameraAccessException In case the camera device is no longer connected or has 1177 * encountered a fatal error. 1178 * @see #createCaptureSession(List, CameraCaptureSession.StateCallback, Handler) 1179 * @see #createCaptureSessionByOutputConfigurations 1180 * @see #createReprocessableCaptureSession 1181 * @see #createConstrainedHighSpeedCaptureSession 1182 * @see OutputConfiguration#setDynamicRangeProfile 1183 * @see android.hardware.camera2.params.DynamicRangeProfiles 1184 */ createCaptureSession( SessionConfiguration config)1185 public void createCaptureSession( 1186 SessionConfiguration config) throws CameraAccessException { 1187 throw new UnsupportedOperationException("No default implementation"); 1188 } 1189 1190 /** 1191 * <p>Create a {@link CaptureRequest.Builder} for new capture requests, 1192 * initialized with template for a target use case. The settings are chosen 1193 * to be the best options for the specific camera device, so it is not 1194 * recommended to reuse the same request for a different camera device; 1195 * create a builder specific for that device and template and override the 1196 * settings as desired, instead.</p> 1197 * 1198 * @param templateType An enumeration selecting the use case for this request. Not all template 1199 * types are supported on every device. See the documentation for each template type for 1200 * details. 1201 * @return a builder for a capture request, initialized with default 1202 * settings for that template, and no output streams 1203 * 1204 * @throws IllegalArgumentException if the templateType is not supported by 1205 * this device. 1206 * @throws CameraAccessException if the camera device is no longer connected or has 1207 * encountered a fatal error 1208 * @throws IllegalStateException if the camera device has been closed 1209 */ 1210 @NonNull createCaptureRequest(@equestTemplate int templateType)1211 public abstract CaptureRequest.Builder createCaptureRequest(@RequestTemplate int templateType) 1212 throws CameraAccessException; 1213 1214 /** 1215 * <p>Create a {@link CaptureRequest.Builder} for new capture requests, 1216 * initialized with template for a target use case. This methods allows 1217 * clients to pass physical camera ids which can be used to customize the 1218 * request for a specific physical camera. The settings are chosen 1219 * to be the best options for the specific logical camera device. If 1220 * additional physical camera ids are passed, then they will also use the 1221 * same settings template. Clients can further modify individual camera 1222 * settings by calling {@link CaptureRequest.Builder#setPhysicalCameraKey}.</p> 1223 * 1224 * <p>Individual physical camera settings will only be honored for camera session 1225 * that was initialiazed with corresponding physical camera id output configuration 1226 * {@link OutputConfiguration#setPhysicalCameraId} and the same output targets are 1227 * also attached in the request by {@link CaptureRequest.Builder#addTarget}.</p> 1228 * 1229 * <p>The output is undefined for any logical camera streams in case valid physical camera 1230 * settings are attached.</p> 1231 * 1232 * @param templateType An enumeration selecting the use case for this request. Not all template 1233 * types are supported on every device. See the documentation for each template type for 1234 * details. 1235 * @param physicalCameraIdSet A set of physical camera ids that can be used to customize 1236 * the request for a specific physical camera. 1237 * @return a builder for a capture request, initialized with default 1238 * settings for that template, and no output streams 1239 * 1240 * @throws IllegalArgumentException if the templateType is not supported by 1241 * this device, or one of the physical id arguments matches with logical camera id. 1242 * @throws CameraAccessException if the camera device is no longer connected or has 1243 * encountered a fatal error 1244 * @throws IllegalStateException if the camera device has been closed 1245 * 1246 * @see #TEMPLATE_PREVIEW 1247 * @see #TEMPLATE_RECORD 1248 * @see #TEMPLATE_STILL_CAPTURE 1249 * @see #TEMPLATE_VIDEO_SNAPSHOT 1250 * @see #TEMPLATE_MANUAL 1251 * @see CaptureRequest.Builder#setPhysicalCameraKey 1252 * @see CaptureRequest.Builder#getPhysicalCameraKey 1253 */ 1254 @NonNull createCaptureRequest(@equestTemplate int templateType, Set<String> physicalCameraIdSet)1255 public CaptureRequest.Builder createCaptureRequest(@RequestTemplate int templateType, 1256 Set<String> physicalCameraIdSet) throws CameraAccessException { 1257 throw new UnsupportedOperationException("Subclasses must override this method"); 1258 } 1259 1260 /** 1261 * <p>Create a {@link CaptureRequest.Builder} for a new reprocess {@link CaptureRequest} from a 1262 * {@link TotalCaptureResult}. 1263 * 1264 * <p>Each reprocess {@link CaptureRequest} processes one buffer from 1265 * {@link CameraCaptureSession}'s input {@link Surface} to all output {@link Surface Surfaces} 1266 * included in the reprocess capture request. The reprocess input images must be generated from 1267 * one or multiple output images captured from the same camera device. The application can 1268 * provide input images to camera device via {@link android.media.ImageWriter#queueInputImage}. 1269 * The application must use the capture result of one of those output images to create a 1270 * reprocess capture request so that the camera device can use the information to achieve 1271 * optimal reprocess image quality. For camera devices that support only 1 output 1272 * {@link Surface}, submitting a reprocess {@link CaptureRequest} with multiple 1273 * output targets will result in a {@link CaptureFailure}. 1274 * 1275 * @param inputResult The capture result of the output image or one of the output images used 1276 * to generate the reprocess input image for this capture request. 1277 * 1278 * @throws IllegalArgumentException if inputResult is null. 1279 * @throws CameraAccessException if the camera device is no longer connected or has 1280 * encountered a fatal error 1281 * @throws IllegalStateException if the camera device has been closed 1282 * 1283 * @see CaptureRequest.Builder 1284 * @see TotalCaptureResult 1285 * @see CameraDevice#createCaptureSession(android.hardware.camera2.params.SessionConfiguration) 1286 * @see android.media.ImageWriter 1287 */ 1288 @NonNull createReprocessCaptureRequest( @onNull TotalCaptureResult inputResult)1289 public abstract CaptureRequest.Builder createReprocessCaptureRequest( 1290 @NonNull TotalCaptureResult inputResult) throws CameraAccessException; 1291 1292 /** 1293 * Close the connection to this camera device as quickly as possible. 1294 * 1295 * <p>Immediately after this call, all calls to the camera device or active session interface 1296 * will throw a {@link IllegalStateException}, except for calls to close(). Once the device has 1297 * fully shut down, the {@link StateCallback#onClosed} callback will be called, and the camera 1298 * is free to be re-opened.</p> 1299 * 1300 * <p>Immediately after this call, besides the final {@link StateCallback#onClosed} calls, no 1301 * further callbacks from the device or the active session will occur, and any remaining 1302 * submitted capture requests will be discarded, as if 1303 * {@link CameraCaptureSession#abortCaptures} had been called, except that no success or failure 1304 * callbacks will be invoked.</p> 1305 * 1306 */ 1307 @Override close()1308 public abstract void close(); 1309 1310 /** 1311 * Checks whether a particular {@link SessionConfiguration} is supported by the camera device. 1312 * 1313 * <p>This method performs a runtime check of a given {@link SessionConfiguration}. The result 1314 * confirms whether or not the passed session configuration can be successfully used to 1315 * create a camera capture session using 1316 * {@link CameraDevice#createCaptureSession( 1317 * android.hardware.camera2.params.SessionConfiguration)}. 1318 * </p> 1319 * 1320 * <p>The method can be called at any point before, during and after active capture session. 1321 * It must not impact normal camera behavior in any way and must complete significantly 1322 * faster than creating a regular or constrained capture session.</p> 1323 * 1324 * <p>Although this method is faster than creating a new capture session, it is not intended 1325 * to be used for exploring the entire space of supported stream combinations. The available 1326 * mandatory stream combinations 1327 * {@link android.hardware.camera2.params.MandatoryStreamCombination} are better suited for this 1328 * purpose.</p> 1329 * 1330 * <p>Note that session parameters will be ignored and calls to 1331 * {@link SessionConfiguration#setSessionParameters} are not required.</p> 1332 * 1333 * @return {@code true} if the given session configuration is supported by the camera device 1334 * {@code false} otherwise. 1335 * @throws UnsupportedOperationException if the query operation is not supported by the camera 1336 * device 1337 * @throws IllegalArgumentException if the session configuration is invalid 1338 * @throws CameraAccessException if the camera device is no longer connected or has 1339 * encountered a fatal error 1340 * @throws IllegalStateException if the camera device has been closed 1341 */ isSessionConfigurationSupported( @onNull SessionConfiguration sessionConfig)1342 public boolean isSessionConfigurationSupported( 1343 @NonNull SessionConfiguration sessionConfig) throws CameraAccessException { 1344 throw new UnsupportedOperationException("Subclasses must override this method"); 1345 } 1346 1347 /** 1348 * A callback objects for receiving updates about the state of a camera device. 1349 * 1350 * <p>A callback instance must be provided to the {@link CameraManager#openCamera} method to 1351 * open a camera device.</p> 1352 * 1353 * <p>These state updates include notifications about the device completing startup ( 1354 * allowing for {@link #createCaptureSession} to be called), about device 1355 * disconnection or closure, and about unexpected device errors.</p> 1356 * 1357 * <p>Events about the progress of specific {@link CaptureRequest CaptureRequests} are provided 1358 * through a {@link CameraCaptureSession.CaptureCallback} given to the 1359 * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst}, 1360 * {@link CameraCaptureSession#setRepeatingRequest}, or 1361 * {@link CameraCaptureSession#setRepeatingBurst} methods. 1362 * 1363 * @see CameraManager#openCamera 1364 */ 1365 public static abstract class StateCallback { 1366 /** 1367 * An error code that can be reported by {@link #onError} 1368 * indicating that the camera device is in use already. 1369 * 1370 * <p> 1371 * This error can be produced when opening the camera fails due to the camera 1372 * being used by a higher-priority camera API client. 1373 * </p> 1374 * 1375 * @see #onError 1376 */ 1377 public static final int ERROR_CAMERA_IN_USE = 1; 1378 1379 /** 1380 * An error code that can be reported by {@link #onError} 1381 * indicating that the camera device could not be opened 1382 * because there are too many other open camera devices. 1383 * 1384 * <p> 1385 * The system-wide limit for number of open cameras has been reached, 1386 * and more camera devices cannot be opened until previous instances are 1387 * closed. 1388 * </p> 1389 * 1390 * <p> 1391 * This error can be produced when opening the camera fails. 1392 * </p> 1393 * 1394 * @see #onError 1395 */ 1396 public static final int ERROR_MAX_CAMERAS_IN_USE = 2; 1397 1398 /** 1399 * An error code that can be reported by {@link #onError} 1400 * indicating that the camera device could not be opened due to a device 1401 * policy. 1402 * 1403 * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) 1404 * @see #onError 1405 */ 1406 public static final int ERROR_CAMERA_DISABLED = 3; 1407 1408 /** 1409 * An error code that can be reported by {@link #onError} 1410 * indicating that the camera device has encountered a fatal error. 1411 * 1412 * <p>The camera device needs to be re-opened to be used again.</p> 1413 * 1414 * @see #onError 1415 */ 1416 public static final int ERROR_CAMERA_DEVICE = 4; 1417 1418 /** 1419 * An error code that can be reported by {@link #onError} 1420 * indicating that the camera service has encountered a fatal error. 1421 * 1422 * <p>The Android device may need to be shut down and restarted to restore 1423 * camera function, or there may be a persistent hardware problem.</p> 1424 * 1425 * <p>An attempt at recovery <i>may</i> be possible by closing the 1426 * CameraDevice and the CameraManager, and trying to acquire all resources 1427 * again from scratch.</p> 1428 * 1429 * @see #onError 1430 */ 1431 public static final int ERROR_CAMERA_SERVICE = 5; 1432 1433 /** @hide */ 1434 @Retention(RetentionPolicy.SOURCE) 1435 @IntDef(prefix = {"ERROR_"}, value = 1436 {ERROR_CAMERA_IN_USE, 1437 ERROR_MAX_CAMERAS_IN_USE, 1438 ERROR_CAMERA_DISABLED, 1439 ERROR_CAMERA_DEVICE, 1440 ERROR_CAMERA_SERVICE }) 1441 public @interface ErrorCode {}; 1442 1443 /** 1444 * The method called when a camera device has finished opening. 1445 * 1446 * <p>At this point, the camera device is ready to use, and 1447 * {@link CameraDevice#createCaptureSession} can be called to set up the first capture 1448 * session.</p> 1449 * 1450 * @param camera the camera device that has become opened 1451 */ onOpened(@onNull CameraDevice camera)1452 public abstract void onOpened(@NonNull CameraDevice camera); // Must implement 1453 1454 /** 1455 * The method called when a camera device has been closed with 1456 * {@link CameraDevice#close}. 1457 * 1458 * <p>Any attempt to call methods on this CameraDevice in the 1459 * future will throw a {@link IllegalStateException}.</p> 1460 * 1461 * <p>The default implementation of this method does nothing.</p> 1462 * 1463 * @param camera the camera device that has become closed 1464 */ onClosed(@onNull CameraDevice camera)1465 public void onClosed(@NonNull CameraDevice camera) { 1466 // Default empty implementation 1467 } 1468 1469 /** 1470 * The method called when a camera device is no longer available for 1471 * use. 1472 * 1473 * <p>This callback may be called instead of {@link #onOpened} 1474 * if opening the camera fails.</p> 1475 * 1476 * <p>Any attempt to call methods on this CameraDevice will throw a 1477 * {@link CameraAccessException}. The disconnection could be due to a 1478 * change in security policy or permissions; the physical disconnection 1479 * of a removable camera device; or the camera being needed for a 1480 * higher-priority camera API client.</p> 1481 * 1482 * <p>There may still be capture callbacks that are invoked 1483 * after this method is called, or new image buffers that are delivered 1484 * to active outputs.</p> 1485 * 1486 * <p>The default implementation logs a notice to the system log 1487 * about the disconnection.</p> 1488 * 1489 * <p>You should clean up the camera with {@link CameraDevice#close} after 1490 * this happens, as it is not recoverable until the camera can be opened 1491 * again. For most use cases, this will be when the camera again becomes 1492 * {@link CameraManager.AvailabilityCallback#onCameraAvailable available}. 1493 * </p> 1494 * 1495 * @param camera the device that has been disconnected 1496 */ onDisconnected(@onNull CameraDevice camera)1497 public abstract void onDisconnected(@NonNull CameraDevice camera); // Must implement 1498 1499 /** 1500 * The method called when a camera device has encountered a serious error. 1501 * 1502 * <p>This callback may be called instead of {@link #onOpened} 1503 * if opening the camera fails.</p> 1504 * 1505 * <p>This indicates a failure of the camera device or camera service in 1506 * some way. Any attempt to call methods on this CameraDevice in the 1507 * future will throw a {@link CameraAccessException} with the 1508 * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason. 1509 * </p> 1510 * 1511 * <p>There may still be capture completion or camera stream callbacks 1512 * that will be called after this error is received.</p> 1513 * 1514 * <p>You should clean up the camera with {@link CameraDevice#close} after 1515 * this happens. Further attempts at recovery are error-code specific.</p> 1516 * 1517 * @param camera The device reporting the error 1518 * @param error The error code. 1519 * 1520 * @see #ERROR_CAMERA_IN_USE 1521 * @see #ERROR_MAX_CAMERAS_IN_USE 1522 * @see #ERROR_CAMERA_DISABLED 1523 * @see #ERROR_CAMERA_DEVICE 1524 * @see #ERROR_CAMERA_SERVICE 1525 */ onError(@onNull CameraDevice camera, @ErrorCode int error)1526 public abstract void onError(@NonNull CameraDevice camera, 1527 @ErrorCode int error); // Must implement 1528 } 1529 1530 /** 1531 * Set audio restriction mode when this CameraDevice is being used. 1532 * 1533 * <p>Some camera hardware (e.g. devices with optical image stabilization support) 1534 * are sensitive to device vibration and video recordings can be ruined by unexpected sounds. 1535 * Applications can use this method to suppress vibration or sounds coming from 1536 * ringtones, alarms or notifications. 1537 * Other vibration or sounds (e.g. media playback or accessibility) will not be muted.</p> 1538 * 1539 * <p>The mute mode is a system-wide setting. When multiple CameraDevice objects 1540 * are setting different modes, the system will pick a the mode that's union of 1541 * all modes set by CameraDevice. Applications can also use 1542 * {@link #getCameraAudioRestriction} to query current system-wide camera 1543 * mute mode in effect.</p> 1544 * 1545 * <p>The mute settings from this CameraDevice will be automatically removed when the 1546 * CameraDevice is closed or the application is disconnected from the camera.</p> 1547 * 1548 * @param mode An enumeration selecting the audio restriction mode for this camera device. 1549 * 1550 * @throws IllegalArgumentException if the mode is not supported 1551 * 1552 * @throws CameraAccessException if the camera device is no longer connected or has 1553 * encountered a fatal error 1554 * @throws IllegalStateException if the camera device has been closed 1555 * 1556 * @see #getCameraAudioRestriction 1557 */ setCameraAudioRestriction( @AMERA_AUDIO_RESTRICTION int mode)1558 public void setCameraAudioRestriction( 1559 @CAMERA_AUDIO_RESTRICTION int mode) throws CameraAccessException { 1560 throw new UnsupportedOperationException("Subclasses must override this method"); 1561 } 1562 1563 /** 1564 * Get currently applied global camera audio restriction mode. 1565 * 1566 * <p>Application can use this method to retrieve the system-wide camera audio restriction 1567 * settings described in {@link #setCameraAudioRestriction}.</p> 1568 * 1569 * @return The current system-wide mute mode setting in effect 1570 * 1571 * @throws CameraAccessException if the camera device is no longer connected or has 1572 * encountered a fatal error 1573 * @throws IllegalStateException if the camera device has been closed 1574 * 1575 * @see #setCameraAudioRestriction 1576 */ getCameraAudioRestriction()1577 public @CAMERA_AUDIO_RESTRICTION int getCameraAudioRestriction() throws CameraAccessException { 1578 throw new UnsupportedOperationException("Subclasses must override this method"); 1579 } 1580 1581 /** 1582 * To be inherited by android.hardware.camera2.* code only. 1583 * @hide 1584 */ CameraDevice()1585 public CameraDevice() {} 1586 } 1587