core/java/android/hardware/camera2/CameraDevice.java

   1 /*
   2  * Copyright (C) 2013 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package android.hardware.camera2;
  18
  19 import android.hardware.camera2.params.InputConfiguration;
  20 import android.hardware.camera2.params.StreamConfigurationMap;
  21 import android.hardware.camera2.params.OutputConfiguration;
  22 import android.os.Handler;
  23 import android.view.Surface;
  24
  25 import java.util.List;
  26
  27 /**
  28  * <p>The CameraDevice class is a representation of a single camera connected to an
  29  * Android device, allowing for fine-grain control of image capture and
  30  * post-processing at high frame rates.</p>
  31  *
  32  * <p>Your application must declare the
  33  * {@link android.Manifest.permission#CAMERA Camera} permission in its manifest
  34  * in order to access camera devices.</p>
  35  *
  36  * <p>A given camera device may provide support at one of two levels: limited or
  37  * full. If a device only supports the limited level, then Camera2 exposes a
  38  * feature set that is roughly equivalent to the older
  39  * {@link android.hardware.Camera Camera} API, although with a cleaner and more
  40  * efficient interface.  Devices that implement the full level of support
  41  * provide substantially improved capabilities over the older camera
  42  * API. Applications that target the limited level devices will run unchanged on
  43  * the full-level devices; if your application requires a full-level device for
  44  * proper operation, declare the "android.hardware.camera2.full" feature in your
  45  * manifest.</p>
  46  *
  47  * @see CameraManager#openCamera
  48  * @see android.Manifest.permission#CAMERA
  49  */
  50 public abstract class CameraDevice implements AutoCloseable {
  51
  52     /**
  53      * Create a request suitable for a camera preview window. Specifically, this
  54      * means that high frame rate is given priority over the highest-quality
  55      * post-processing. These requests would normally be used with the
  56      * {@link CameraCaptureSession#setRepeatingRequest} method.
  57      * This template is guaranteed to be supported on all camera devices.
  58      *
  59      * @see #createCaptureRequest
  60      */
  61     public static final int TEMPLATE_PREVIEW = 1;
  62
  63     /**
  64      * Create a request suitable for still image capture. Specifically, this
  65      * means prioritizing image quality over frame rate. These requests would
  66      * commonly be used with the {@link CameraCaptureSession#capture} method.
  67      * This template is guaranteed to be supported on all camera devices.
  68      *
  69      * @see #createCaptureRequest
  70      */
  71     public static final int TEMPLATE_STILL_CAPTURE = 2;
  72
  73     /**
  74      * Create a request suitable for video recording. Specifically, this means
  75      * that a stable frame rate is used, and post-processing is set for
  76      * recording quality. These requests would commonly be used with the
  77      * {@link CameraCaptureSession#setRepeatingRequest} method.
  78      * This template is guaranteed to be supported on all camera devices.
  79      *
  80      * @see #createCaptureRequest
  81      */
  82     public static final int TEMPLATE_RECORD  = 3;
  83
  84     /**
  85      * Create a request suitable for still image capture while recording
  86      * video. Specifically, this means maximizing image quality without
  87      * disrupting the ongoing recording. These requests would commonly be used
  88      * with the {@link CameraCaptureSession#capture} method while a request based on
  89      * {@link #TEMPLATE_RECORD} is is in use with {@link CameraCaptureSession#setRepeatingRequest}.
  90      * This template is guaranteed to be supported on all camera devices except
  91      * legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}
  92      * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY})
  93      *
  94      * @see #createCaptureRequest
  95      */
  96     public static final int TEMPLATE_VIDEO_SNAPSHOT = 4;
  97
  98     /**
  99      * Create a request suitable for zero shutter lag still capture. This means
 100      * means maximizing image quality without compromising preview frame rate.
 101      * AE/AWB/AF should be on auto mode.
 102      * This template is guaranteed to be supported on camera devices that support the
 103      * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_OPAQUE_REPROCESSING OPAQUE_REPROCESSING}
 104      * capability or the
 105      * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_YUV_REPROCESSING YUV_REPROCESSING}
 106      * capability.
 107      *
 108      * @see #createCaptureRequest
 109      */
 110     public static final int TEMPLATE_ZERO_SHUTTER_LAG = 5;
 111
 112     /**
 113      * A basic template for direct application control of capture
 114      * parameters. All automatic control is disabled (auto-exposure, auto-white
 115      * balance, auto-focus), and post-processing parameters are set to preview
 116      * quality. The manual capture parameters (exposure, sensitivity, and so on)
 117      * are set to reasonable defaults, but should be overriden by the
 118      * application depending on the intended use case.
 119      * This template is guaranteed to be supported on camera devices that support the
 120      * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR MANUAL_SENSOR}
 121      * capability.
 122      *
 123      * @see #createCaptureRequest
 124      */
 125     public static final int TEMPLATE_MANUAL = 6;
 126
 127     /**
 128      * Get the ID of this camera device.
 129      *
 130      * <p>This matches the ID given to {@link CameraManager#openCamera} to instantiate this
 131      * this camera device.</p>
 132      *
 133      * <p>This ID can be used to query the camera device's {@link
 134      * CameraCharacteristics fixed properties} with {@link
 135      * CameraManager#getCameraCharacteristics}.</p>
 136      *
 137      * <p>This method can be called even if the device has been closed or has encountered
 138      * a serious error.</p>
 139      *
 140      * @return the ID for this camera device
 141      *
 142      * @see CameraManager#getCameraCharacteristics
 143      * @see CameraManager#getCameraIdList
 144      */
 145     public abstract String getId();
 146
 147     /**
 148      * <p>Create a new camera capture session by providing the target output set of Surfaces to the
 149      * camera device.</p>
 150      *
 151      * <p>The active capture session determines the set of potential output Surfaces for
 152      * the camera device for each capture request. A given request may use all
 153      * or only some of the outputs. Once the CameraCaptureSession is created, requests can be
 154      * can be submitted with {@link CameraCaptureSession#capture capture},
 155      * {@link CameraCaptureSession#captureBurst captureBurst},
 156      * {@link CameraCaptureSession#setRepeatingRequest setRepeatingRequest}, or
 157      * {@link CameraCaptureSession#setRepeatingBurst setRepeatingBurst}.</p>
 158      *
 159      * <p>Surfaces suitable for inclusion as a camera output can be created for
 160      * various use cases and targets:</p>
 161      *
 162      * <ul>
 163      *
 164      * <li>For drawing to a {@link android.view.SurfaceView SurfaceView}: Once the SurfaceView's
 165      *   Surface is {@link android.view.SurfaceHolder.Callback#surfaceCreated created}, set the size
 166      *   of the Surface with {@link android.view.SurfaceHolder#setFixedSize} to be one of the sizes
 167      *   returned by {@link StreamConfigurationMap#getOutputSizes(Class)
 168      *   getOutputSizes(SurfaceHolder.class)} and then obtain the Surface by calling {@link
 169      *   android.view.SurfaceHolder#getSurface}. If the size is not set by the application, it will
 170      *   be rounded to the nearest supported size less than 1080p, by the camera device.</li>
 171      *
 172      * <li>For accessing through an OpenGL texture via a {@link android.graphics.SurfaceTexture
 173      *   SurfaceTexture}: Set the size of the SurfaceTexture with {@link
 174      *   android.graphics.SurfaceTexture#setDefaultBufferSize} to be one of the sizes returned by
 175      *   {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(SurfaceTexture.class)}
 176      *   before creating a Surface from the SurfaceTexture with {@link Surface#Surface}. If the size
 177      *   is not set by the application, it will be set to be the smallest supported size less than
 178      *   1080p, by the camera device.</li>
 179      *
 180      * <li>For recording with {@link android.media.MediaCodec}: Call
 181      *   {@link android.media.MediaCodec#createInputSurface} after configuring
 182      *   the media codec to use one of the sizes returned by
 183      *   {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaCodec.class)}
 184      *   </li>
 185      *
 186      * <li>For recording with {@link android.media.MediaRecorder}: Call
 187      *   {@link android.media.MediaRecorder#getSurface} after configuring the media recorder to use
 188      *   one of the sizes returned by
 189      *   {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(MediaRecorder.class)},
 190      *   or configuring it to use one of the supported
 191      *   {@link android.media.CamcorderProfile CamcorderProfiles}.</li>
 192      *
 193      * <li>For efficient YUV processing with {@link android.renderscript}:
 194      *   Create a RenderScript
 195      *   {@link android.renderscript.Allocation Allocation} with a supported YUV
 196      *   type, the IO_INPUT flag, and one of the sizes returned by
 197      *   {@link StreamConfigurationMap#getOutputSizes(Class) getOutputSizes(Allocation.class)},
 198      *   Then obtain the Surface with
 199      *   {@link android.renderscript.Allocation#getSurface}.</li>
 200      *
 201      * <li>For access to RAW, uncompressed YUV, or compressed JPEG data in the application: Create an
 202      *   {@link android.media.ImageReader} object with one of the supported output formats given by
 203      *   {@link StreamConfigurationMap#getOutputFormats()}, setting its size to one of the
 204      *   corresponding supported sizes by passing the chosen output format into
 205      *   {@link StreamConfigurationMap#getOutputSizes(int)}. Then obtain a
 206      *   {@link android.view.Surface} from it with {@link android.media.ImageReader#getSurface()}.
 207      *   If the ImageReader size is not set to a supported size, it will be rounded to a supported
 208      *   size less than 1080p by the camera device.
 209      *   </li>
 210      *
 211      * </ul>
 212      *
 213      * <p>The camera device will query each Surface's size and formats upon this
 214      * call, so they must be set to a valid setting at this time.</p>
 215      *
 216      * <p>It can take several hundred milliseconds for the session's configuration to complete,
 217      * since camera hardware may need to be powered on or reconfigured. Once the configuration is
 218      * complete and the session is ready to actually capture data, the provided
 219      * {@link CameraCaptureSession.StateCallback}'s
 220      * {@link CameraCaptureSession.StateCallback#onConfigured} callback will be called.</p>
 221      *
 222      * <p>If a prior CameraCaptureSession already exists when a new one is created, the previous
 223      * session is closed. Any in-progress capture requests made on the prior session will be
 224      * completed before the new session is configured and is able to start capturing its own
 225      * requests. To minimize the transition time, the {@link CameraCaptureSession#abortCaptures}
 226      * call can be used to discard the remaining requests for the prior capture session before a new
 227      * one is created. Note that once the new session is created, the old one can no longer have its
 228      * captures aborted.</p>
 229      *
 230      * <p>Using larger resolution outputs, or more outputs, can result in slower
 231      * output rate from the device.</p>
 232      *
 233      * <p>Configuring a session with an empty or null list will close the current session, if
 234      * any. This can be used to release the current session's target surfaces for another use.</p>
 235      *
 236      * <p>While any of the sizes from {@link StreamConfigurationMap#getOutputSizes} can be used when
 237      * a single output stream is configured, a given camera device may not be able to support all
 238      * combination of sizes, formats, and targets when multiple outputs are configured at once.  The
 239      * tables below list the maximum guaranteed resolutions for combinations of streams and targets,
 240      * given the capabilities of the camera device.</p>
 241      *
 242      * <p>If an application tries to create a session using a set of targets that exceed the limits
 243      * described in the below tables, one of three possibilities may occur. First, the session may
 244      * be successfully created and work normally. Second, the session may be successfully created,
 245      * but the camera device won't meet the frame rate guarantees as described in
 246      * {@link StreamConfigurationMap#getOutputMinFrameDuration}. Or third, if the output set
 247      * cannot be used at all, session creation will fail entirely, with
 248      * {@link CameraCaptureSession.StateListener#onConfigureFailed} being invoked.</p>
 249      *
 250      * <p>For the type column, {@code PRIV} refers to any target whose available sizes are found
 251      * using {@link StreamConfigurationMap#getOutputSizes(Class)} with no direct application-visible
 252      * format, {@code YUV} refers to a target Surface using the
 253      * {@link android.graphics.ImageFormat#YUV_420_888} format, {@code JPEG} refers to the
 254      * {@link android.graphics.ImageFormat#JPEG} format, and {@code RAW} refers to the
 255      * {@link android.graphics.ImageFormat#RAW_SENSOR} format.</p>
 256      *
 257      * <p>For the maximum size column, {@code PREVIEW} refers to the best size match to the
 258      * device's screen resolution, or to 1080p ({@code 1920x1080}), whichever is
 259      * smaller. {@code RECORD} refers to the camera device's maximum supported recording resolution,
 260      * as determined by {@link android.media.CamcorderProfile}. And {@code MAXIMUM} refers to the
 261      * camera device's maximum output resolution for that format or target from
 262      * {@link StreamConfigurationMap#getOutputSizes}.</p>
 263      *
 264      * <p>To use these tables, determine the number and the formats/targets of outputs needed, and
 265      * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes
 266      * that can be used; it is guaranteed that for those targets, the listed sizes and anything
 267      * smaller from the list given by {@link StreamConfigurationMap#getOutputSizes} can be
 268      * successfully used to create a session.  For example, if a row indicates that a 8 megapixel
 269      * (MP) YUV_420_888 output can be used together with a 2 MP {@code PRIV} output, then a session
 270      * can be created with targets {@code [8 MP YUV, 2 MP PRIV]} or targets {@code [2 MP YUV, 2 MP
 271      * PRIV]}; but a session with targets {@code [8 MP YUV, 4 MP PRIV]}, targets {@code [4 MP YUV, 4
 272      * MP PRIV]}, or targets {@code [8 MP PRIV, 2 MP YUV]} would not be guaranteed to work, unless
 273      * some other row of the table lists such a combination.</p>
 274      *
 275      * <style scoped>
 276      *  #rb { border-right-width: thick; }
 277      * </style>
 278      * <p>Legacy devices ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}
 279      * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at
 280      * least the following stream combinations:
 281      *
 282      * <table>
 283      * <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr>
 284      * <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>
 285      * <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>
 286      * <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>
 287      * <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>
 288      * <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>
 289      * <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>
 290      * <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>
 291      * <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>
 292      * <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>
 293      * <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>
 294      * </table><br>
 295      * </p>
 296      *
 297      * <p>Limited-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}
 298      * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices
 299      * support at least the following stream combinations in addition to those for
 300      * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices:
 301      *
 302      * <table>
 303      * <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr>
 304      * <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>
 305      * <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>
 306      * <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>
 307      * <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>
 308      * <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>
 309      * <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>
 310      * <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>
 311      * <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>
 312      * </table><br>
 313      * </p>
 314      *
 315      * <p>FULL-capability ({@link CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL}
 316      * {@code == }{@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices
 317      * support at least the following stream combinations in addition to those for
 318      * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices:
 319      *
 320      * <table>
 321      * <tr><th colspan="7">FULL-capability additional guaranteed configurations</th></tr>
 322      * <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>
 323      * <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>
 324      * <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>
 325      * <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>
 326      * <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>
 327      * <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>
 328      * <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>
 329      * <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>
 330      * </table><br>
 331      * </p>
 332      *
 333      * <p>RAW-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes
 334      * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support
 335      * at least the following stream combinations on both
 336      * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and
 337      * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices:
 338      *
 339      * <table>
 340      * <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr>
 341      * <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>
 342      * <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>
 343      * <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>
 344      * <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>
 345      * <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>
 346      * <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>
 347      * <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>
 348      * <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>
 349      * <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>
 350      * <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>
 351      * </table><br>
 352      * </p>
 353      *
 354      * <p>BURST-capability ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES} includes
 355      * {@link CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices
 356      * support at least the below stream combinations in addition to those for
 357      * {@link CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices. Note that all
 358      * FULL-level devices support the BURST capability, and the below list is a strict subset of the
 359      * list for FULL-level devices, so this table is only relevant for LIMITED-level devices that
 360      * support the BURST_CAPTURE capability.
 361      *
 362      * <table>
 363      * <tr><th colspan="5">BURST-capability additional guaranteed configurations</th></tr>
 364      * <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>
 365      * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr>
 366      * <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>
 367      * <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>
 368      * <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>
 369      * </table><br>
 370      * </p>
 371      *
 372      * <p>Since the capabilities of camera devices vary greatly, a given camera device may support
 373      * target combinations with sizes outside of these guarantees, but this can only be tested for
 374      * by attempting to create a session with such targets.</p>
 375      *
 376      * @param outputs The new set of Surfaces that should be made available as
 377      *                targets for captured image data.
 378      * @param callback The callback to notify about the status of the new capture session.
 379      * @param handler The handler on which the callback should be invoked, or {@code null} to use
 380      *                the current thread's {@link android.os.Looper looper}.
 381      *
 382      * @throws IllegalArgumentException if the set of output Surfaces do not meet the requirements,
 383      *                                  the callback is null, or the handler is null but the current
 384      *                                  thread has no looper.
 385      * @throws CameraAccessException if the camera device is no longer connected or has
 386      *                               encountered a fatal error
 387      * @throws IllegalStateException if the camera device has been closed
 388      *
 389      * @see CameraCaptureSession
 390      * @see StreamConfigurationMap#getOutputFormats()
 391      * @see StreamConfigurationMap#getOutputSizes(int)
 392      * @see StreamConfigurationMap#getOutputSizes(Class)
 393      */
 394     public abstract void createCaptureSession(List<Surface> outputs,
 395             CameraCaptureSession.StateCallback callback, Handler handler)
 396             throws CameraAccessException;
 397
 398     /**
 399      * <p>Create a new camera capture session by providing the target output set of Surfaces and
 400      * its corresponding surface configuration to the camera device.</p>
 401      *
 402      * @see #createCaptureSession
 403      * @see OutputConfiguration
 404      *
 405      * @hide
 406      */
 407     public abstract void createCaptureSessionByOutputConfiguration(
 408             List<OutputConfiguration> outputConfigurations,
 409             CameraCaptureSession.StateCallback callback, Handler handler)
 410             throws CameraAccessException;
 411     /**
 412      * Create a new reprocessible camera capture session by providing the desired reprocessing
 413      * input Surface configuration and the target output set of Surfaces to the camera device.
 414      *
 415      * <p>If a camera device supports YUV reprocessing
 416      * ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_YUV_REPROCESSING}) or OPAQUE
 417      * reprocessing
 418      * ({@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES_OPAQUE_REPROCESSING}), besides
 419      * the capture session created via {@link #createCaptureSession}, the application can also
 420      * create a reprocessible capture session to submit reprocess capture requests in addition to
 421      * regular capture requests. A reprocess capture request takes the next available buffer from
 422      * the session's input Surface, and sends it through the camera device's processing pipeline
 423      * again, to produce buffers for the request's target output Surfaces. No new image data is
 424      * captured for a reprocess request. However the input buffer provided by
 425      * the application must be captured previously by the same camera device in the same session
 426      * directly (e.g. for Zero-Shutter-Lag use case) or indirectly (e.g. combining multiple output
 427      * images).</p>
 428      *
 429      * <p>The active reprocessible capture session determines an input {@link Surface} and the set
 430      * of potential output Surfaces for the camera devices for each capture request. The application
 431      * can use {@link #createCaptureRequest} to create regular capture requests to capture new
 432      * images from the camera device, and use {@link #createReprocessCaptureRequest} to create
 433      * reprocess capture requests to process buffers from the input {@link Surface}. A request may
 434      * use all or only some of the outputs. All the output Surfaces in one capture request will come
 435      * from the same source, either from a new capture by the camera device, or from the input
 436      * Surface depending on if the request is a reprocess capture request.</p>
 437      *
 438      * <p>Input formats and sizes supported by the camera device can be queried via
 439      * {@link StreamConfigurationMap#getInputFormats} and
 440      * {@link StreamConfigurationMap#getInputSizes}. For each supported input format, the camera
 441      * device supports a set of output formats and sizes for reprocessing that can be queried via
 442      * {@link StreamConfigurationMap#getValidOutputFormatsForInput} and
 443      * {@link StreamConfigurationMap#getOutputSizes}. While output Surfaces with formats that
 444      * aren't valid reprocess output targets for the input configuration can be part of a session,
 445      * they cannot be used as targets for a reprocessing request.</p>
 446      *
 447      * <p>Since the application cannot access {@link android.graphics.ImageFormat#PRIVATE} images
 448      * directly, an output Surface created by {@link android.media.ImageReader#newOpaqueInstance}
 449      * will be considered as intended to be used for reprocessing input and thus the
 450      * {@link android.media.ImageReader} size must match one of the supported input sizes for
 451      * {@link android.graphics.ImageFormat#PRIVATE} format. Otherwise, creating a reprocessible
 452      * capture session will fail.</p>
 453      *
 454      * @param inputConfig The configuration for the input {@link Surface}
 455      * @param outputs The new set of Surfaces that should be made available as
 456      *                targets for captured image data.
 457      * @param callback The callback to notify about the status of the new capture session.
 458      * @param handler The handler on which the callback should be invoked, or {@code null} to use
 459      *                the current thread's {@link android.os.Looper looper}.
 460      *
 461      * @throws IllegalArgumentException if the input configuration is null or not supported, the set
 462      *                                  of output Surfaces do not meet the requirements, the
 463      *                                  callback is null, or the handler is null but the current
 464      *                                  thread has no looper.
 465      * @throws CameraAccessException if the camera device is no longer connected or has
 466      *                               encountered a fatal error
 467      * @throws IllegalStateException if the camera device has been closed
 468      *
 469      * @see CameraCaptureSession
 470      * @see StreamConfigurationMap#getInputFormats
 471      * @see StreamConfigurationMap#getInputSizes
 472      * @see StreamConfigurationMap#getValidOutputFormatsForInput
 473      * @see StreamConfigurationMap#getOutputSizes
 474      * @see android.media.ImageWriter
 475      * @see android.media.ImageReader
 476      */
 477     public abstract void createReprocessibleCaptureSession(InputConfiguration inputConfig,
 478             List<Surface> outputs, CameraCaptureSession.StateCallback callback, Handler handler)
 479             throws CameraAccessException;
 480
 481     /**
 482      * <p>Create a {@link CaptureRequest.Builder} for new capture requests,
 483      * initialized with template for a target use case. The settings are chosen
 484      * to be the best options for the specific camera device, so it is not
 485      * recommended to reuse the same request for a different camera device;
 486      * create a builder specific for that device and template and override the
 487      * settings as desired, instead.</p>
 488      *
 489      * @param templateType An enumeration selecting the use case for this
 490      * request; one of the CameraDevice.TEMPLATE_ values. Not all template
 491      * types are supported on every device. See the documentation for each
 492      * template type for details.
 493      * @return a builder for a capture request, initialized with default
 494      * settings for that template, and no output streams
 495      *
 496      * @throws IllegalArgumentException if the templateType is not supported by
 497      * this device.
 498      * @throws CameraAccessException if the camera device is no longer connected or has
 499      *                               encountered a fatal error
 500      * @throws IllegalStateException if the camera device has been closed
 501      *
 502      * @see #TEMPLATE_PREVIEW
 503      * @see #TEMPLATE_RECORD
 504      * @see #TEMPLATE_STILL_CAPTURE
 505      * @see #TEMPLATE_VIDEO_SNAPSHOT
 506      * @see #TEMPLATE_MANUAL
 507      */
 508     public abstract CaptureRequest.Builder createCaptureRequest(int templateType)
 509             throws CameraAccessException;
 510
 511     /**
 512      * <p>Create a {@link CaptureRequest.Builder} for a new reprocess {@link CaptureRequest} from a
 513      * {@link TotalCaptureResult}.
 514      *
 515      * <p>Each reprocess {@link CaptureRequest} processes one buffer from
 516      * {@link CameraCaptureSession}'s input {@link Surface} to all output {@link Surface Surfaces}
 517      * included in the reprocess capture request. The reprocess input images must be generated from
 518      * one or multiple output images captured from the same camera device. The application can
 519      * provide input images to camera device via
 520      * {{@link android.media.ImageWriter#queueInputImage ImageWriter#queueInputImage}}.
 521      * The application must use the capture result of one of those output images to create a
 522      * reprocess capture request so that the camera device can use the information to achieve
 523      * optimal reprocess image quality.
 524      *
 525      * @param inputResult The capture result of the output image or one of the output images used
 526      *                       to generate the reprocess input image for this capture request.
 527      *
 528      * @throws IllegalArgumentException if inputResult is null.
 529      * @throws CameraAccessException if the camera device is no longer connected or has
 530      *                               encountered a fatal error
 531      * @throws IllegalStateException if the camera device has been closed
 532      *
 533      * @see CaptureRequest.Builder
 534      * @see TotalCaptureResult
 535      * @see CameraDevice#createReprocessibleCaptureSession
 536      * @see android.media.ImageWriter
 537      */
 538     public abstract CaptureRequest.Builder createReprocessCaptureRequest(
 539             TotalCaptureResult inputResult) throws CameraAccessException;
 540
 541     /**
 542      * Close the connection to this camera device as quickly as possible.
 543      *
 544      * <p>Immediately after this call, all calls to the camera device or active session interface
 545      * will throw a {@link IllegalStateException}, except for calls to close(). Once the device has
 546      * fully shut down, the {@link StateCallback#onClosed} callback will be called, and the camera
 547      * is free to be re-opened.</p>
 548      *
 549      * <p>Immediately after this call, besides the final {@link StateCallback#onClosed} calls, no
 550      * further callbacks from the device or the active session will occur, and any remaining
 551      * submitted capture requests will be discarded, as if
 552      * {@link CameraCaptureSession#abortCaptures} had been called, except that no success or failure
 553      * callbacks will be invoked.</p>
 554      *
 555      */
 556     @Override
 557     public abstract void close();
 558
 559     /**
 560      * A callback objects for receiving updates about the state of a camera device.
 561      *
 562      * <p>A callback instance must be provided to the {@link CameraManager#openCamera} method to
 563      * open a camera device.</p>
 564      *
 565      * <p>These state updates include notifications about the device completing startup (
 566      * allowing for {@link #createCaptureSession} to be called), about device
 567      * disconnection or closure, and about unexpected device errors.</p>
 568      *
 569      * <p>Events about the progress of specific {@link CaptureRequest CaptureRequests} are provided
 570      * through a {@link CameraCaptureSession.CaptureCallback} given to the
 571      * {@link CameraCaptureSession#capture}, {@link CameraCaptureSession#captureBurst},
 572      * {@link CameraCaptureSession#setRepeatingRequest}, or
 573      * {@link CameraCaptureSession#setRepeatingBurst} methods.
 574      *
 575      * @see CameraManager#openCamera
 576      */
 577     public static abstract class StateCallback {
 578        /**
 579          * An error code that can be reported by {@link #onError}
 580          * indicating that the camera device is in use already.
 581          *
 582          * <p>
 583          * This error can be produced when opening the camera fails.
 584          * </p>
 585          *
 586          * @see #onError
 587          */
 588         public static final int ERROR_CAMERA_IN_USE = 1;
 589
 590         /**
 591          * An error code that can be reported by {@link #onError}
 592          * indicating that the camera device could not be opened
 593          * because there are too many other open camera devices.
 594          *
 595          * <p>
 596          * The system-wide limit for number of open cameras has been reached,
 597          * and more camera devices cannot be opened until previous instances are
 598          * closed.
 599          * </p>
 600          *
 601          * <p>
 602          * This error can be produced when opening the camera fails.
 603          * </p>
 604          *
 605          * @see #onError
 606          */
 607         public static final int ERROR_MAX_CAMERAS_IN_USE = 2;
 608
 609         /**
 610          * An error code that can be reported by {@link #onError}
 611          * indicating that the camera device could not be opened due to a device
 612          * policy.
 613          *
 614          * @see android.app.admin.DevicePolicyManager#setCameraDisabled(android.content.ComponentName, boolean)
 615          * @see #onError
 616          */
 617         public static final int ERROR_CAMERA_DISABLED = 3;
 618
 619        /**
 620          * An error code that can be reported by {@link #onError}
 621          * indicating that the camera device has encountered a fatal error.
 622          *
 623          * <p>The camera device needs to be re-opened to be used again.</p>
 624          *
 625          * @see #onError
 626          */
 627         public static final int ERROR_CAMERA_DEVICE = 4;
 628
 629         /**
 630          * An error code that can be reported by {@link #onError}
 631          * indicating that the camera service has encountered a fatal error.
 632          *
 633          * <p>The Android device may need to be shut down and restarted to restore
 634          * camera function, or there may be a persistent hardware problem.</p>
 635          *
 636          * <p>An attempt at recovery <i>may</i> be possible by closing the
 637          * CameraDevice and the CameraManager, and trying to acquire all resources
 638          * again from scratch.</p>
 639          *
 640          * @see #onError
 641          */
 642         public static final int ERROR_CAMERA_SERVICE = 5;
 643
 644         /**
 645          * The method called when a camera device has finished opening.
 646          *
 647          * <p>At this point, the camera device is ready to use, and
 648          * {@link CameraDevice#createCaptureSession} can be called to set up the first capture
 649          * session.</p>
 650          *
 651          * @param camera the camera device that has become opened
 652          */
 653         public abstract void onOpened(CameraDevice camera); // Must implement
 654
 655         /**
 656          * The method called when a camera device has been closed with
 657          * {@link CameraDevice#close}.
 658          *
 659          * <p>Any attempt to call methods on this CameraDevice in the
 660          * future will throw a {@link IllegalStateException}.</p>
 661          *
 662          * <p>The default implementation of this method does nothing.</p>
 663          *
 664          * @param camera the camera device that has become closed
 665          */
 666         public void onClosed(CameraDevice camera) {
 667             // Default empty implementation
 668         }
 669
 670         /**
 671          * The method called when a camera device is no longer available for
 672          * use.
 673          *
 674          * <p>This callback may be called instead of {@link #onOpened}
 675          * if opening the camera fails.</p>
 676          *
 677          * <p>Any attempt to call methods on this CameraDevice will throw a
 678          * {@link CameraAccessException}. The disconnection could be due to a
 679          * change in security policy or permissions; the physical disconnection
 680          * of a removable camera device; or the camera being needed for a
 681          * higher-priority use case.</p>
 682          *
 683          * <p>There may still be capture callbacks that are invoked
 684          * after this method is called, or new image buffers that are delivered
 685          * to active outputs.</p>
 686          *
 687          * <p>The default implementation logs a notice to the system log
 688          * about the disconnection.</p>
 689          *
 690          * <p>You should clean up the camera with {@link CameraDevice#close} after
 691          * this happens, as it is not recoverable until opening the camera again
 692          * after it becomes {@link CameraManager.AvailabilityCallback#onCameraAvailable available}.
 693          * </p>
 694          *
 695          * @param camera the device that has been disconnected
 696          */
 697         public abstract void onDisconnected(CameraDevice camera); // Must implement
 698
 699         /**
 700          * The method called when a camera device has encountered a serious error.
 701          *
 702          * <p>This callback may be called instead of {@link #onOpened}
 703          * if opening the camera fails.</p>
 704          *
 705          * <p>This indicates a failure of the camera device or camera service in
 706          * some way. Any attempt to call methods on this CameraDevice in the
 707          * future will throw a {@link CameraAccessException} with the
 708          * {@link CameraAccessException#CAMERA_ERROR CAMERA_ERROR} reason.
 709          * </p>
 710          *
 711          * <p>There may still be capture completion or camera stream callbacks
 712          * that will be called after this error is received.</p>
 713          *
 714          * <p>You should clean up the camera with {@link CameraDevice#close} after
 715          * this happens. Further attempts at recovery are error-code specific.</p>
 716          *
 717          * @param camera The device reporting the error
 718          * @param error The error code, one of the
 719          *     {@code StateCallback.ERROR_*} values.
 720          *
 721          * @see #ERROR_CAMERA_DEVICE
 722          * @see #ERROR_CAMERA_SERVICE
 723          * @see #ERROR_CAMERA_DISABLED
 724          * @see #ERROR_CAMERA_IN_USE
 725          */
 726         public abstract void onError(CameraDevice camera, int error); // Must implement
 727     }
 728
 729     /**
 730      * Temporary for migrating to Callback naming
 731      * @hide
 732      */
 733     public static abstract class StateListener extends StateCallback {
 734     }
 735
 736     /**
 737      * To be inherited by android.hardware.camera2.* code only.
 738      * @hide
 739      */
 740     public CameraDevice() {}
 741 }