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 | |
Igor Murashkin | 9c59517 | 2014-05-12 13:56:20 -0700 | [diff] [blame] | 19 | import android.hardware.camera2.params.StreamConfigurationMap; |
| 20 | import android.graphics.ImageFormat; |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 21 | import android.os.Handler; |
Zhijun He | 599be61 | 2013-09-27 13:43:25 -0700 | [diff] [blame] | 22 | import android.view.Surface; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 23 | |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 24 | import java.util.List; |
| 25 | |
| 26 | /** |
Igor Murashkin | 21547d6 | 2014-06-04 15:21:42 -0700 | [diff] [blame] | 27 | * <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] | 28 | * Android device, allowing for fine-grain control of image capture and |
| 29 | * post-processing at high frame rates.</p> |
| 30 | * |
| 31 | * <p>Your application must declare the |
| 32 | * {@link android.Manifest.permission#CAMERA Camera} permission in its manifest |
| 33 | * in order to access camera devices.</p> |
| 34 | * |
| 35 | * <p>A given camera device may provide support at one of two levels: limited or |
| 36 | * full. If a device only supports the limited level, then Camera2 exposes a |
| 37 | * feature set that is roughly equivalent to the older |
| 38 | * {@link android.hardware.Camera Camera} API, although with a cleaner and more |
| 39 | * efficient interface. Devices that implement the full level of support |
| 40 | * provide substantially improved capabilities over the older camera |
| 41 | * API. Applications that target the limited level devices will run unchanged on |
| 42 | * the full-level devices; if your application requires a full-level device for |
| 43 | * proper operation, declare the "android.hardware.camera2.full" feature in your |
| 44 | * manifest.</p> |
| 45 | * |
| 46 | * @see CameraManager#openCamera |
| 47 | * @see android.Manifest.permission#CAMERA |
| 48 | */ |
Igor Murashkin | 21547d6 | 2014-06-04 15:21:42 -0700 | [diff] [blame] | 49 | public abstract class CameraDevice implements AutoCloseable { |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 50 | |
| 51 | /** |
| 52 | * Create a request suitable for a camera preview window. Specifically, this |
| 53 | * means that high frame rate is given priority over the highest-quality |
| 54 | * post-processing. These requests would normally be used with the |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 55 | * {@link CameraCaptureSession#setRepeatingRequest} method. |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 56 | * |
| 57 | * @see #createCaptureRequest |
| 58 | */ |
| 59 | public static final int TEMPLATE_PREVIEW = 1; |
| 60 | |
| 61 | /** |
Zhijun He | b8b77bf | 2013-06-28 16:30:12 -0700 | [diff] [blame] | 62 | * Create a request suitable for still image capture. Specifically, this |
| 63 | * means prioritizing image quality over frame rate. These requests would |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 64 | * commonly be used with the {@link CameraCaptureSession#capture} method. |
Zhijun He | b8b77bf | 2013-06-28 16:30:12 -0700 | [diff] [blame] | 65 | * |
| 66 | * @see #createCaptureRequest |
| 67 | */ |
| 68 | public static final int TEMPLATE_STILL_CAPTURE = 2; |
| 69 | |
| 70 | /** |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 71 | * Create a request suitable for video recording. Specifically, this means |
| 72 | * that a stable frame rate is used, and post-processing is set for |
| 73 | * recording quality. These requests would commonly be used with the |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 74 | * {@link CameraCaptureSession#setRepeatingRequest} method. |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 75 | * |
| 76 | * @see #createCaptureRequest |
| 77 | */ |
Zhijun He | b8b77bf | 2013-06-28 16:30:12 -0700 | [diff] [blame] | 78 | public static final int TEMPLATE_RECORD = 3; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 79 | |
| 80 | /** |
| 81 | * Create a request suitable for still image capture while recording |
| 82 | * video. Specifically, this means maximizing image quality without |
| 83 | * disrupting the ongoing recording. These requests would commonly be used |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 84 | * with the {@link CameraCaptureSession#capture} method while a request based on |
| 85 | * {@link #TEMPLATE_RECORD} is is in use with {@link CameraCaptureSession#setRepeatingRequest}. |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 86 | * |
| 87 | * @see #createCaptureRequest |
| 88 | */ |
| 89 | public static final int TEMPLATE_VIDEO_SNAPSHOT = 4; |
| 90 | |
| 91 | /** |
Zhijun He | bbae94a | 2013-09-13 11:32:20 -0700 | [diff] [blame] | 92 | * Create a request suitable for zero shutter lag still capture. This means |
| 93 | * means maximizing image quality without compromising preview frame rate. |
| 94 | * AE/AWB/AF should be on auto mode. |
| 95 | * |
| 96 | * @see #createCaptureRequest |
Zhijun He | bbae94a | 2013-09-13 11:32:20 -0700 | [diff] [blame] | 97 | */ |
| 98 | public static final int TEMPLATE_ZERO_SHUTTER_LAG = 5; |
| 99 | |
| 100 | /** |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 101 | * A basic template for direct application control of capture |
| 102 | * parameters. All automatic control is disabled (auto-exposure, auto-white |
| 103 | * balance, auto-focus), and post-processing parameters are set to preview |
| 104 | * quality. The manual capture parameters (exposure, sensitivity, and so on) |
| 105 | * are set to reasonable defaults, but should be overriden by the |
| 106 | * application depending on the intended use case. |
| 107 | * |
| 108 | * @see #createCaptureRequest |
| 109 | */ |
Zhijun He | bbae94a | 2013-09-13 11:32:20 -0700 | [diff] [blame] | 110 | public static final int TEMPLATE_MANUAL = 6; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 111 | |
| 112 | /** |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 113 | * Get the ID of this camera device. |
| 114 | * |
| 115 | * <p>This matches the ID given to {@link CameraManager#openCamera} to instantiate this |
| 116 | * this camera device.</p> |
| 117 | * |
| 118 | * <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] | 119 | * CameraCharacteristics fixed properties} with {@link |
| 120 | * CameraManager#getCameraCharacteristics}.</p> |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 121 | * |
| 122 | * <p>This method can be called even if the device has been closed or has encountered |
| 123 | * a serious error.</p> |
| 124 | * |
| 125 | * @return the ID for this camera device |
| 126 | * |
Igor Murashkin | 68f4006 | 2013-09-10 12:15:54 -0700 | [diff] [blame] | 127 | * @see CameraManager#getCameraCharacteristics |
Zhijun He | 599be61 | 2013-09-27 13:43:25 -0700 | [diff] [blame] | 128 | * @see CameraManager#getCameraIdList |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 129 | */ |
Igor Murashkin | 21547d6 | 2014-06-04 15:21:42 -0700 | [diff] [blame] | 130 | public abstract String getId(); |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 131 | |
| 132 | /** |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 133 | * <p>Create a new camera capture session by providing the target output set of Surfaces to the |
| 134 | * camera device.</p> |
| 135 | * |
| 136 | * <p>The active capture session determines the set of potential output Surfaces for |
| 137 | * the camera device for each capture request. A given request may use all |
| 138 | * or a only some of the outputs. Once the CameraCaptureSession is created, requests can be |
| 139 | * can be submitted with {@link CameraCaptureSession#capture capture}, |
| 140 | * {@link CameraCaptureSession#captureBurst captureBurst}, |
| 141 | * {@link CameraCaptureSession#setRepeatingRequest setRepeatingRequest}, or |
| 142 | * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}.</p> |
| 143 | * |
| 144 | * <p>Surfaces suitable for inclusion as a camera output can be created for |
| 145 | * various use cases and targets:</p> |
| 146 | * |
| 147 | * <ul> |
| 148 | * |
Eino-Ville Talvala | 5ae1ca5 | 2014-06-12 16:46:58 -0700 | [diff] [blame] | 149 | * <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] | 150 | * Surface is {@link android.view.SurfaceHolder.Callback#surfaceCreated created}, set the size |
| 151 | * of the Surface with {@link android.view.SurfaceHolder#setFixedSize} to be one of the sizes |
| 152 | * returned by {@link StreamConfigurationMap#getOutputSizes(Class) |
| 153 | * getOutputSizes(SurfaceHolder.class)} and then obtain the Surface by calling {@link |
| 154 | * android.view.SurfaceHolder#getSurface}. If the size is not set by the application, it will |
| 155 | * 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] | 156 | * |
Eino-Ville Talvala | fa0b9a0 | 2015-01-20 12:30:59 -0800 | [diff] [blame] | 157 | * <li>For accessing through an OpenGL texture via a {@link android.graphics.SurfaceTexture |
| 158 | * SurfaceTexture}: Set the size of the SurfaceTexture with {@link |
| 159 | * 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] | 160 | * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(SurfaceTexture.class)} |
Eino-Ville Talvala | fa0b9a0 | 2015-01-20 12:30:59 -0800 | [diff] [blame] | 161 | * before creating a Surface from the SurfaceTexture with {@link Surface#Surface}. If the size |
| 162 | * is not set by the application, it will be set to be the smallest supported size less than |
| 163 | * 1080p, by the camera device.</li> |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 164 | * |
| 165 | * <li>For recording with {@link android.media.MediaCodec}: Call |
| 166 | * {@link android.media.MediaCodec#createInputSurface} after configuring |
| 167 | * the media codec to use one of the sizes returned by |
| 168 | * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaCodec.class)} |
| 169 | * </li> |
| 170 | * |
| 171 | * <li>For recording with {@link android.media.MediaRecorder}: Call |
| 172 | * {@link android.media.MediaRecorder#getSurface} after configuring the media recorder to use |
| 173 | * one of the sizes returned by |
| 174 | * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaRecorder.class)}, |
| 175 | * or configuring it to use one of the supported |
| 176 | * {@link android.media.CamcorderProfile CamcorderProfiles}.</li> |
| 177 | * |
| 178 | * <li>For efficient YUV processing with {@link android.renderscript}: |
| 179 | * Create a RenderScript |
| 180 | * {@link android.renderscript.Allocation Allocation} with a supported YUV |
| 181 | * type, the IO_INPUT flag, and one of the sizes returned by |
| 182 | * {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(Allocation.class)}, |
| 183 | * Then obtain the Surface with |
| 184 | * {@link android.renderscript.Allocation#getSurface}.</li> |
| 185 | * |
Martin Storsjo | e686047 | 2014-11-19 11:58:03 +0200 | [diff] [blame^] | 186 | * <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] | 187 | * {@link android.media.ImageReader} object with one of the supported output formats given by |
| 188 | * {@link StreamConfigurationMap#getOutputFormats()}, setting its size to one of the |
| 189 | * corresponding supported sizes by passing the chosen output format into |
| 190 | * {@link StreamConfigurationMap#getOutputSizes(int)}. Then obtain a |
| 191 | * {@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] | 192 | * If the ImageReader size is not set to a supported size, it will be rounded to a supported |
| 193 | * size less than 1080p by the camera device. |
Sol Boucher | b8cee51 | 2014-06-11 16:35:57 -0700 | [diff] [blame] | 194 | * </li> |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 195 | * |
| 196 | * </ul> |
| 197 | * |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 198 | * <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] | 199 | * 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] | 200 | * |
| 201 | * <p>It can take several hundred milliseconds for the session's configuration to complete, |
| 202 | * since camera hardware may need to be powered on or reconfigured. Once the configuration is |
| 203 | * 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] | 204 | * {@link CameraCaptureSession.StateCallback}'s |
| 205 | * {@link CameraCaptureSession.StateCallback#onConfigured} callback will be called.</p> |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 206 | * |
| 207 | * <p>If a prior CameraCaptureSession already exists when a new one is created, the previous |
| 208 | * session is closed. Any in-progress capture requests made on the prior session will be |
| 209 | * completed before the new session is configured and is able to start capturing its own |
| 210 | * requests. To minimize the transition time, the {@link CameraCaptureSession#abortCaptures} |
| 211 | * call can be used to discard the remaining requests for the prior capture session before a new |
| 212 | * one is created. Note that once the new session is created, the old one can no longer have its |
| 213 | * captures aborted.</p> |
| 214 | * |
| 215 | * <p>Using larger resolution outputs, or more outputs, can result in slower |
| 216 | * output rate from the device.</p> |
| 217 | * |
| 218 | * <p>Configuring a session with an empty or null list will close the current session, if |
| 219 | * any. This can be used to release the current session's target surfaces for another use.</p> |
| 220 | * |
Eino-Ville Talvala | f3621f3 | 2014-08-26 14:53:39 -0700 | [diff] [blame] | 221 | * <p>While any of the sizes from {@link StreamConfigurationMap#getOutputSizes} can be used when |
| 222 | * a single output stream is configured, a given camera device may not be able to support all |
| 223 | * combination of sizes, formats, and targets when multiple outputs are configured at once. The |
| 224 | * tables below list the maximum guaranteed resolutions for combinations of streams and targets, |
| 225 | * given the capabilities of the camera device.</p> |
| 226 | * |
| 227 | * <p>If an application tries to create a session using a set of targets that exceed the limits |
| 228 | * described in the below tables, one of three possibilities may occur. First, the session may |
| 229 | * be successfully created and work normally. Second, the session may be successfully created, |
| 230 | * but the camera device won't meet the frame rate guarantees as described in |
| 231 | * {@link StreamConfigurationMap#getOutputMinFrameDuration}. Or third, if the output set |
| 232 | * cannot be used at all, session creation will fail entirely, with |
| 233 | * {@link CameraCaptureSession.StateListener#onConfigureFailed} being invoked.</p> |
| 234 | * |
| 235 | * <p>For the type column, {@code PRIV} refers to any target whose available sizes are found |
| 236 | * using {@link StreamConfigurationMap#getOutputSizes(Class)} with no direct application-visible |
| 237 | * format, {@code YUV} refers to a target Surface using the |
| 238 | * {@link android.graphics.ImageFormat#YUV_420_888} format, {@code JPEG} refers to the |
| 239 | * {@link android.graphics.ImageFormat#JPEG} format, and {@code RAW} refers to the |
| 240 | * {@link android.graphics.ImageFormat#RAW_SENSOR} format.</p> |
| 241 | * |
| 242 | * <p>For the maximum size column, {@code PREVIEW} refers to the best size match to the |
| 243 | * device's screen resolution, or to 1080p ({@code 1920x1080}), whichever is |
| 244 | * smaller. {@code RECORD} refers to the camera device's maximum supported recording resolution, |
| 245 | * as determined by {@link android.media.CamcorderProfile}. And {@code MAXIMUM} refers to the |
| 246 | * camera device's maximum output resolution for that format or target from |
| 247 | * {@link StreamConfigurationMap#getOutputSizes}.</p> |
| 248 | * |
| 249 | * <p>To use these tables, determine the number and the formats/targets of outputs needed, and |
| 250 | * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes |
| 251 | * that can be used; it is guaranteed that for those targets, the listed sizes and anything |
| 252 | * smaller from the list given by {@link StreamConfigurationMap#getOutputSizes} can be |
| 253 | * successfully used to create a session. For example, if a row indicates that a 8 megapixel |
| 254 | * (MP) YUV_420_888 output can be used together with a 2 MP {@code PRIV} output, then a session |
| 255 | * can be created with targets {@code [8 MP YUV, 2 MP PRIV]} or targets {@code [2 MP YUV, 2 MP |
| 256 | * PRIV]}; but a session with targets {@code [8 MP YUV, 4 MP PRIV]}, targets {@code [4 MP YUV, 4 |
| 257 | * MP PRIV]}, or targets {@code [8 MP PRIV, 2 MP YUV]} would not be guaranteed to work, unless |
| 258 | * some other row of the table lists such a combination.</p> |
| 259 | * |
| 260 | * <style scoped> |
| 261 | * #rb { border-right-width: thick; } |
| 262 | * </style> |
| 263 | * <p>Legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} |
| 264 | * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at |
| 265 | * least the following stream combinations: |
| 266 | * |
| 267 | * <table> |
| 268 | * <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr> |
| 269 | * <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> |
| 270 | * <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> |
| 271 | * <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> |
| 272 | * <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> |
| 273 | * <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> |
| 274 | * <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> |
| 275 | * <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> |
| 276 | * <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> |
| 277 | * <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> |
| 278 | * <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> |
| 279 | * </table><br> |
| 280 | * </p> |
| 281 | * |
| 282 | * <p>Limited-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} |
| 283 | * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices |
| 284 | * support at least the following stream combinations in addition to those for |
| 285 | * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: |
| 286 | * |
| 287 | * <table> |
| 288 | * <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr> |
| 289 | * <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> |
| 290 | * <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> |
| 291 | * <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> |
| 292 | * <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> |
| 293 | * <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> |
| 294 | * <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> |
| 295 | * <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> |
| 296 | * <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> |
| 297 | * </table><br> |
| 298 | * </p> |
| 299 | * |
| 300 | * <p>FULL-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL} |
| 301 | * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices |
| 302 | * support at least the following stream combinations in addition to those for |
| 303 | * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: |
| 304 | * |
| 305 | * <table> |
| 306 | * <tr><th colspan="7">FULL-capability additional guaranteed configurations</th></tr> |
| 307 | * <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> |
| 308 | * <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> |
| 309 | * <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> |
| 310 | * <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> |
| 311 | * <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> |
| 312 | * <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> |
| 313 | * <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> |
| 314 | * <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> |
| 315 | * </table><br> |
| 316 | * </p> |
| 317 | * |
| 318 | * <p>RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes |
| 319 | * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support |
| 320 | * at least the following stream combinations on both |
| 321 | * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and |
| 322 | * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: |
| 323 | * |
| 324 | * <table> |
| 325 | * <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr> |
| 326 | * <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> |
| 327 | * <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> |
| 328 | * <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> |
| 329 | * <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> |
| 330 | * <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> |
| 331 | * <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> |
| 332 | * <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> |
| 333 | * <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> |
| 334 | * <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> |
| 335 | * <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> |
| 336 | * </table><br> |
| 337 | * </p> |
| 338 | * |
Eino-Ville Talvala | 126a746 | 2014-11-04 16:31:01 -0800 | [diff] [blame] | 339 | * <p>BURST-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes |
| 340 | * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices |
| 341 | * support at least the below stream combinations in addition to those for |
| 342 | * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices. Note that all |
| 343 | * FULL-level devices support the BURST capability, and the below list is a strict subset of the |
| 344 | * list for FULL-level devices, so this table is only relevant for LIMITED-level devices that |
| 345 | * support the BURST_CAPTURE capability. |
| 346 | * |
| 347 | * <table> |
| 348 | * <tr><th colspan="5">BURST-capability additional guaranteed configurations</th></tr> |
| 349 | * <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> |
| 350 | * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> |
| 351 | * <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> |
| 352 | * <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> |
| 353 | * <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> |
| 354 | * </table><br> |
| 355 | * </p> |
| 356 | * |
Eino-Ville Talvala | f3621f3 | 2014-08-26 14:53:39 -0700 | [diff] [blame] | 357 | * <p>Since the capabilities of camera devices vary greatly, a given camera device may support |
| 358 | * target combinations with sizes outside of these guarantees, but this can only be tested for |
| 359 | * by attempting to create a session with such targets.</p> |
| 360 | * |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 361 | * @param outputs The new set of Surfaces that should be made available as |
| 362 | * targets for captured image data. |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 363 | * @param callback The callback to notify about the status of the new capture session. |
| 364 | * @param handler The handler on which the callback should be invoked, or {@code null} to use |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 365 | * the current thread's {@link android.os.Looper looper}. |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 366 | * |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 367 | * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements, |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 368 | * the callback is null, or the handler is null but the current |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 369 | * thread has no looper. |
| 370 | * @throws CameraAccessException if the camera device is no longer connected or has |
| 371 | * encountered a fatal error |
| 372 | * @throws IllegalStateException if the camera device has been closed |
| 373 | * |
| 374 | * @see CameraCaptureSession |
| 375 | * @see StreamConfigurationMap#getOutputFormats() |
| 376 | * @see StreamConfigurationMap#getOutputSizes(int) |
| 377 | * @see StreamConfigurationMap#getOutputSizes(Class) |
| 378 | */ |
Igor Murashkin | 21547d6 | 2014-06-04 15:21:42 -0700 | [diff] [blame] | 379 | public abstract void createCaptureSession(List<Surface> outputs, |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 380 | CameraCaptureSession.StateCallback callback, Handler handler) |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 381 | throws CameraAccessException; |
| 382 | |
| 383 | /** |
Eino-Ville Talvala | 70c2207 | 2013-08-27 12:09:04 -0700 | [diff] [blame] | 384 | * <p>Create a {@link CaptureRequest.Builder} for new capture requests, |
| 385 | * initialized with template for a target use case. The settings are chosen |
| 386 | * to be the best options for the specific camera device, so it is not |
| 387 | * recommended to reuse the same request for a different camera device; |
| 388 | * create a builder specific for that device and template and override the |
| 389 | * settings as desired, instead.</p> |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 390 | * |
| 391 | * @param templateType An enumeration selecting the use case for this |
| 392 | * request; one of the CameraDevice.TEMPLATE_ values. |
Eino-Ville Talvala | 70c2207 | 2013-08-27 12:09:04 -0700 | [diff] [blame] | 393 | * @return a builder for a capture request, initialized with default |
| 394 | * settings for that template, and no output streams |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 395 | * |
| 396 | * @throws IllegalArgumentException if the templateType is not in the list |
| 397 | * of supported templates. |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 398 | * @throws CameraAccessException if the camera device is no longer connected or has |
| 399 | * encountered a fatal error |
| 400 | * @throws IllegalStateException if the camera device has been closed |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 401 | * |
| 402 | * @see #TEMPLATE_PREVIEW |
| 403 | * @see #TEMPLATE_RECORD |
| 404 | * @see #TEMPLATE_STILL_CAPTURE |
| 405 | * @see #TEMPLATE_VIDEO_SNAPSHOT |
| 406 | * @see #TEMPLATE_MANUAL |
| 407 | */ |
Igor Murashkin | 21547d6 | 2014-06-04 15:21:42 -0700 | [diff] [blame] | 408 | public abstract CaptureRequest.Builder createCaptureRequest(int templateType) |
Igor Murashkin | 7072550 | 2013-06-25 20:27:06 +0000 | [diff] [blame] | 409 | throws CameraAccessException; |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 410 | |
| 411 | /** |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 412 | * Close the connection to this camera device as quickly as possible. |
Eino-Ville Talvala | 868d904 | 2013-10-03 11:15:21 -0700 | [diff] [blame] | 413 | * |
Eino-Ville Talvala | cca00c6 | 2014-05-14 10:53:20 -0700 | [diff] [blame] | 414 | * <p>Immediately after this call, all calls to the camera device or active session interface |
| 415 | * 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] | 416 | * 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] | 417 | * is free to be re-opened.</p> |
Eino-Ville Talvala | 868d904 | 2013-10-03 11:15:21 -0700 | [diff] [blame] | 418 | * |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 419 | * <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] | 420 | * further callbacks from the device or the active session will occur, and any remaining |
| 421 | * submitted capture requests will be discarded, as if |
| 422 | * {@link CameraCaptureSession#abortCaptures} had been called, except that no success or failure |
| 423 | * callbacks will be invoked.</p> |
Eino-Ville Talvala | 868d904 | 2013-10-03 11:15:21 -0700 | [diff] [blame] | 424 | * |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 425 | */ |
Igor Murashkin | e363fbb | 2013-06-25 20:26:06 +0000 | [diff] [blame] | 426 | @Override |
Igor Murashkin | 21547d6 | 2014-06-04 15:21:42 -0700 | [diff] [blame] | 427 | public abstract void close(); |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 428 | |
| 429 | /** |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 430 | * 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] | 431 | * |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 432 | * <p>A callback instance must be provided to the {@link CameraManager#openCamera} method to |
| 433 | * open a camera device.</p> |
Eino-Ville Talvala | 868d904 | 2013-10-03 11:15:21 -0700 | [diff] [blame] | 434 | * |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 435 | * <p>These state updates include notifications about the device completing startup ( |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 436 | * allowing for {@link #createCaptureSession} to be called), about device |
| 437 | * disconnection or closure, and about unexpected device errors.</p> |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 438 | * |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 439 | * <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] | 440 | * through a {@link CameraCaptureSession.CaptureCallback} given to the |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 441 | * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst}, |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 442 | * {@link CameraCaptureSession#setRepeatingRequest}, or |
| 443 | * {@link CameraCaptureSession#setRepeatingBurst} methods. |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 444 | * |
Eino-Ville Talvala | 868d904 | 2013-10-03 11:15:21 -0700 | [diff] [blame] | 445 | * @see CameraManager#openCamera |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 446 | */ |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 447 | public static abstract class StateCallback { |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 448 | /** |
| 449 | * An error code that can be reported by {@link #onError} |
| 450 | * indicating that the camera device is in use already. |
| 451 | * |
| 452 | * <p> |
| 453 | * This error can be produced when opening the camera fails. |
| 454 | * </p> |
| 455 | * |
| 456 | * @see #onError |
| 457 | */ |
| 458 | public static final int ERROR_CAMERA_IN_USE = 1; |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 459 | |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 460 | /** |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 461 | * An error code that can be reported by {@link #onError} |
| 462 | * indicating that the camera device could not be opened |
| 463 | * because there are too many other open camera devices. |
| 464 | * |
| 465 | * <p> |
| 466 | * The system-wide limit for number of open cameras has been reached, |
| 467 | * and more camera devices cannot be opened until previous instances are |
| 468 | * closed. |
| 469 | * </p> |
| 470 | * |
| 471 | * <p> |
| 472 | * This error can be produced when opening the camera fails. |
| 473 | * </p> |
| 474 | * |
| 475 | * @see #onError |
| 476 | */ |
| 477 | public static final int ERROR_MAX_CAMERAS_IN_USE = 2; |
| 478 | |
| 479 | /** |
| 480 | * An error code that can be reported by {@link #onError} |
| 481 | * indicating that the camera device could not be opened due to a device |
| 482 | * policy. |
| 483 | * |
| 484 | * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean) |
| 485 | * @see #onError |
| 486 | */ |
| 487 | public static final int ERROR_CAMERA_DISABLED = 3; |
| 488 | |
| 489 | /** |
| 490 | * An error code that can be reported by {@link #onError} |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 491 | * indicating that the camera device has encountered a fatal error. |
| 492 | * |
| 493 | * <p>The camera device needs to be re-opened to be used again.</p> |
| 494 | * |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 495 | * @see #onError |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 496 | */ |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 497 | public static final int ERROR_CAMERA_DEVICE = 4; |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 498 | |
| 499 | /** |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 500 | * An error code that can be reported by {@link #onError} |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 501 | * indicating that the camera service has encountered a fatal error. |
| 502 | * |
| 503 | * <p>The Android device may need to be shut down and restarted to restore |
| 504 | * camera function, or there may be a persistent hardware problem.</p> |
| 505 | * |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 506 | * <p>An attempt at recovery <i>may</i> be possible by closing the |
| 507 | * CameraDevice and the CameraManager, and trying to acquire all resources |
| 508 | * again from scratch.</p> |
| 509 | * |
| 510 | * @see #onError |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 511 | */ |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 512 | public static final int ERROR_CAMERA_SERVICE = 5; |
| 513 | |
| 514 | /** |
| 515 | * The method called when a camera device has finished opening. |
| 516 | * |
Eino-Ville Talvala | b67a3b3 | 2014-06-06 13:07:20 -0700 | [diff] [blame] | 517 | * <p>At this point, the camera device is ready to use, and |
| 518 | * {@link CameraDevice#createCaptureSession} can be called to set up the first capture |
| 519 | * session.</p> |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 520 | * |
| 521 | * @param camera the camera device that has become opened |
| 522 | */ |
| 523 | public abstract void onOpened(CameraDevice camera); // Must implement |
| 524 | |
| 525 | /** |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 526 | * The method called when a camera device has been closed with |
| 527 | * {@link CameraDevice#close}. |
| 528 | * |
| 529 | * <p>Any attempt to call methods on this CameraDevice in the |
| 530 | * future will throw a {@link IllegalStateException}.</p> |
| 531 | * |
| 532 | * <p>The default implementation of this method does nothing.</p> |
| 533 | * |
| 534 | * @param camera the camera device that has become closed |
| 535 | */ |
| 536 | public void onClosed(CameraDevice camera) { |
| 537 | // Default empty implementation |
| 538 | } |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 539 | |
| 540 | /** |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 541 | * The method called when a camera device is no longer available for |
| 542 | * use. |
| 543 | * |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 544 | * <p>This callback may be called instead of {@link #onOpened} |
| 545 | * if opening the camera fails.</p> |
| 546 | * |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 547 | * <p>Any attempt to call methods on this CameraDevice will throw a |
| 548 | * {@link CameraAccessException}. The disconnection could be due to a |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 549 | * change in security policy or permissions; the physical disconnection |
| 550 | * of a removable camera device; or the camera being needed for a |
| 551 | * higher-priority use case.</p> |
| 552 | * |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 553 | * <p>There may still be capture callbacks that are invoked |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 554 | * after this method is called, or new image buffers that are delivered |
| 555 | * to active outputs.</p> |
| 556 | * |
| 557 | * <p>The default implementation logs a notice to the system log |
| 558 | * about the disconnection.</p> |
| 559 | * |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 560 | * <p>You should clean up the camera with {@link CameraDevice#close} after |
| 561 | * this happens, as it is not recoverable until opening the camera again |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 562 | * after it becomes {@link CameraManager.AvailabilityCallback#onCameraAvailable available}. |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 563 | * </p> |
| 564 | * |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 565 | * @param camera the device that has been disconnected |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 566 | */ |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 567 | public abstract void onDisconnected(CameraDevice camera); // Must implement |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 568 | |
| 569 | /** |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 570 | * The method called when a camera device has encountered a serious error. |
| 571 | * |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 572 | * <p>This callback may be called instead of {@link #onOpened} |
| 573 | * if opening the camera fails.</p> |
| 574 | * |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 575 | * <p>This indicates a failure of the camera device or camera service in |
| 576 | * some way. Any attempt to call methods on this CameraDevice in the |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 577 | * future will throw a {@link CameraAccessException} with the |
| 578 | * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason. |
| 579 | * </p> |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 580 | * |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 581 | * <p>There may still be capture completion or camera stream callbacks |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 582 | * that will be called after this error is received.</p> |
| 583 | * |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 584 | * <p>You should clean up the camera with {@link CameraDevice#close} after |
| 585 | * this happens. Further attempts at recovery are error-code specific.</p> |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 586 | * |
| 587 | * @param camera The device reporting the error |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 588 | * @param error The error code, one of the |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 589 | * {@code StateCallback.ERROR_*} values. |
Eino-Ville Talvala | 4af73c2 | 2013-08-14 10:35:46 -0700 | [diff] [blame] | 590 | * |
| 591 | * @see #ERROR_CAMERA_DEVICE |
| 592 | * @see #ERROR_CAMERA_SERVICE |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 593 | * @see #ERROR_CAMERA_DISABLED |
| 594 | * @see #ERROR_CAMERA_IN_USE |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 595 | */ |
Igor Murashkin | 5c9eaf6 | 2013-09-10 19:35:24 -0700 | [diff] [blame] | 596 | public abstract void onError(CameraDevice camera, int error); // Must implement |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 597 | } |
Igor Murashkin | 21547d6 | 2014-06-04 15:21:42 -0700 | [diff] [blame] | 598 | |
| 599 | /** |
Eino-Ville Talvala | fd88743 | 2014-09-04 13:07:40 -0700 | [diff] [blame] | 600 | * Temporary for migrating to Callback naming |
| 601 | * @hide |
| 602 | */ |
| 603 | public static abstract class StateListener extends StateCallback { |
| 604 | } |
| 605 | |
| 606 | /** |
Igor Murashkin | 21547d6 | 2014-06-04 15:21:42 -0700 | [diff] [blame] | 607 | * To be inherited by android.hardware.camera2.* code only. |
| 608 | * @hide |
| 609 | */ |
| 610 | public CameraDevice() {} |
Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 611 | } |