package.html revision b942b05093d2b1cee59ac73196a4b99962f10add
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 18individual camera devices connected to an Android device. It replaces 19the deprecated {@link android.hardware.Camera} class.</p> 20 21<p>This package models a camera device as a pipeline, which takes in 22input requests for capturing a single frame, captures the single image 23per the request, and then outputs one capture result metadata packet, 24plus a set of output image buffers for the request. The requests are 25processed in-order, and multiple requests can be in flight at 26once. Since the camera device is a pipeline with multiple stages, 27having multiple requests in flight is required to maintain full 28framerate 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 34CameraDevices} provide a set of static property information that 35describes the hardware device and the available settings and output 36parameters for the device. This information is provided through the 37{@link android.hardware.camera2.CameraCharacteristics} object, and is 38available through {@link 39android.hardware.camera2.CameraManager#getCameraCharacteristics}</p> 40 41<p>To capture or stream images from a camera device, the application 42must first create a {@link 43android.hardware.camera2.CameraCaptureSession camera capture session} 44with a set of output Surfaces for use with the camera device, with 45{@link 46android.hardware.camera2.CameraDevice#createCaptureSession}. Each 47Surface has to be pre-configured with an {@link 48android.hardware.camera2.params.StreamConfigurationMap appropriate 49size and format} (if applicable) to match the sizes and formats 50available from the camera device. A target Surface can be obtained 51from 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 59android.view.SurfaceView} or {@link android.view.TextureView} (via its 60{@link android.graphics.SurfaceTexture}). Capture of JPEG images or 61RAW buffers for {@link android.hardware.camera2.DngCreator} can be 62done with {@link android.media.ImageReader} with the {@link 63android.graphics.ImageFormat#JPEG} and {@link 64android.graphics.ImageFormat#RAW_SENSOR} formats. Application-driven 65processing of camera data in RenderScript, OpenGL ES, or directly in 66managed or native code is best done through {@link 67android.renderscript.Allocation} with a YUV {@link 68android.renderscript.Type}, {@link android.graphics.SurfaceTexture}, 69and {@link android.media.ImageReader} with a {@link 70android.graphics.ImageFormat#YUV_420_888} format, respectively.</p> 71 72<p>The application then needs to construct a {@link 73android.hardware.camera2.CaptureRequest}, which defines all the 74capture parameters needed by a camera device to capture a single 75image. The request also lists which of the configured output Surfaces 76should be used as targets for this capture. The CameraDevice has a 77{@link android.hardware.camera2.CameraDevice#createCaptureRequest 78factory method} for creating a {@link 79android.hardware.camera2.CaptureRequest.Builder request builder} for a 80given use case, which is optimized for the Android device the 81application is running on.</p> 82 83<p>Once the request has been set up, it can be handed to the active 84capture session either for a one-shot {@link 85android.hardware.camera2.CameraCaptureSession#capture capture} or for 86an endlessly {@link 87android.hardware.camera2.CameraCaptureSession#setRepeatingRequest 88repeating} use. Both methods also have a variant that accepts a list 89of requests to use as a burst capture / repeating burst. Repeating 90requests have a lower priority than captures, so a request submitted 91through <code>capture()</code> while there's a repeating request 92configured will be captured before any new instances of the currently 93repeating (burst) capture will begin capture.</p> 94 95<p>After processing a request, the camera device will produce a {@link 96android.hardware.camera2.TotalCaptureResult} object, which contains 97information about the state of the camera device at time of capture, 98and the final settings used. These may vary somewhat from the request, 99if rounding or resolving contradictory parameters was necessary. The 100camera device will also send a frame of image data into each of the 101output {@code Surfaces} included in the request. These are produced 102asynchronously relative to the output CaptureResult, sometimes 103substantially later.</p> 104 105</BODY> 106</HTML> 107