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