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