1 <!-- Copyright (C) 2013 The Android Open Source Project 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 --> 15 <HTML> 16 <BODY> 17 <p>The android.hardware.camera2 package provides an interface to 18 individual camera devices connected to an Android device. It replaces 19 the deprecated {@link android.hardware.Camera} class.</p> 20 21 <p>This package models a camera device as a pipeline, which takes in 22 input requests for capturing a single frame, captures the single image 23 per the request, and then outputs one capture result metadata packet, 24 plus a set of output image buffers for the request. The requests are 25 processed in-order, and multiple requests can be in flight at 26 once. Since the camera device is a pipeline with multiple stages, 27 having multiple requests in flight is required to maintain full 28 framerate on most Android devices.</p> 29 30 <p>To enumerate, query, and open available camera devices, obtain a 31 {@link android.hardware.camera2.CameraManager} instance.</p> 32 33 <p>Individual {@link android.hardware.camera2.CameraDevice 34 CameraDevices} provide a set of static property information that 35 describes the hardware device and the available settings and output 36 parameters for the device. This information is provided through the 37 {@link android.hardware.camera2.CameraCharacteristics} object, and is 38 available through {@link 39 android.hardware.camera2.CameraManager#getCameraCharacteristics}</p> 40 41 <p>To capture or stream images from a camera device, the application 42 must first create a {@link 43 android.hardware.camera2.CameraCaptureSession camera capture session} 44 with a set of output Surfaces for use with the camera device, with 45 {@link 46 android.hardware.camera2.CameraDevice#createCaptureSession}. Each 47 Surface has to be pre-configured with an {@link 48 android.hardware.camera2.params.StreamConfigurationMap appropriate 49 size and format} (if applicable) to match the sizes and formats 50 available from the camera device. A target Surface can be obtained 51 from a variety of classes, including {@link android.view.SurfaceView}, 52 {@link android.graphics.SurfaceTexture} via 53 {@link android.view.Surface#Surface(SurfaceTexture)}, 54 {@link android.media.MediaCodec}, {@link android.media.MediaRecorder}, 55 {@link android.renderscript.Allocation}, and {@link android.media.ImageReader}. 56 </p> 57 58 <p>Generally, camera preview images are sent to {@link 59 android.view.SurfaceView} or {@link android.view.TextureView} (via its 60 {@link android.graphics.SurfaceTexture}). Capture of JPEG images or 61 RAW buffers for {@link android.hardware.camera2.DngCreator} can be 62 done with {@link android.media.ImageReader} with the {@link 63 android.graphics.ImageFormat#JPEG} and {@link 64 android.graphics.ImageFormat#RAW_SENSOR} formats. Application-driven 65 processing of camera data in RenderScript, OpenGL ES, or directly in 66 managed or native code is best done through {@link 67 android.renderscript.Allocation} with a YUV {@link 68 android.renderscript.Type}, {@link android.graphics.SurfaceTexture}, 69 and {@link android.media.ImageReader} with a {@link 70 android.graphics.ImageFormat#YUV_420_888} format, respectively.</p> 71 72 <p>The application then needs to construct a {@link 73 android.hardware.camera2.CaptureRequest}, which defines all the 74 capture parameters needed by a camera device to capture a single 75 image. The request also lists which of the configured output Surfaces 76 should be used as targets for this capture. The CameraDevice has a 77 {@link android.hardware.camera2.CameraDevice#createCaptureRequest 78 factory method} for creating a {@link 79 android.hardware.camera2.CaptureRequest.Builder request builder} for a 80 given use case, which is optimized for the Android device the 81 application is running on.</p> 82 83 <p>Once the request has been set up, it can be handed to the active 84 capture session either for a one-shot {@link 85 android.hardware.camera2.CameraCaptureSession#capture capture} or for 86 an endlessly {@link 87 android.hardware.camera2.CameraCaptureSession#setRepeatingRequest 88 repeating} use. Both methods also have a variant that accepts a list 89 of requests to use as a burst capture / repeating burst. Repeating 90 requests have a lower priority than captures, so a request submitted 91 through <code>capture()</code> while there's a repeating request 92 configured will be captured before any new instances of the currently 93 repeating (burst) capture will begin capture.</p> 94 95 <p>After processing a request, the camera device will produce a {@link 96 android.hardware.camera2.TotalCaptureResult} object, which contains 97 information about the state of the camera device at time of capture, 98 and the final settings used. These may vary somewhat from the request, 99 if rounding or resolving contradictory parameters was necessary. The 100 camera device will also send a frame of image data into each of the 101 output {@code Surfaces} included in the request. These are produced 102 asynchronously relative to the output CaptureResult, sometimes 103 substantially later.</p> 104 105 </BODY> 106 </HTML> 107
