| <!-- Copyright (C) 2013 The Android Open Source Project |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <HTML> |
| <BODY> |
| <p>The android.hardware.camera2 package provides an interface to |
| individual camera devices connected to an Android device. It replaces |
| the deprecated {@link android.hardware.Camera} class.</p> |
| |
| <p>This package models a camera device as a pipeline, which takes in |
| input requests for capturing a single frame, captures the single image |
| per the request, and then outputs one capture result metadata packet, |
| plus a set of output image buffers for the request. The requests are |
| processed in-order, and multiple requests can be in flight at |
| once. Since the camera device is a pipeline with multiple stages, |
| having multiple requests in flight is required to maintain full |
| framerate on most Android devices.</p> |
| |
| <p>To enumerate, query, and open available camera devices, obtain a |
| {@link android.hardware.camera2.CameraManager} instance.</p> |
| |
| <p>Individual {@link android.hardware.camera2.CameraDevice |
| CameraDevices} provide a set of static property information that |
| describes the hardware device and the available settings and output |
| parameters for the device. This information is provided through the |
| {@link android.hardware.camera2.CameraCharacteristics} object, and is |
| available through {@link |
| android.hardware.camera2.CameraManager#getCameraCharacteristics}</p> |
| |
| <p>To capture or stream images from a camera device, the application |
| must first create a {@link |
| android.hardware.camera2.CameraCaptureSession camera capture session} |
| with a set of output Surfaces for use with the camera device, with |
| {@link |
| android.hardware.camera2.CameraDevice#createCaptureSession}. Each |
| Surface has to be pre-configured with an {@link |
| android.hardware.camera2.params.StreamConfigurationMap appropriate |
| size and format} (if applicable) to match the sizes and formats |
| available from the camera device. A target Surface can be obtained |
| from a variety of classes, including {@link android.view.SurfaceView}, |
| {@link android.graphics.SurfaceTexture} via |
| {@link android.view.Surface#Surface(SurfaceTexture)}, |
| {@link android.media.MediaCodec}, {@link android.media.MediaRecorder}, |
| {@link android.renderscript.Allocation}, and {@link android.media.ImageReader}. |
| </p> |
| |
| <p>Generally, camera preview images are sent to {@link |
| android.view.SurfaceView} or {@link android.view.TextureView} (via its |
| {@link android.graphics.SurfaceTexture}). Capture of JPEG images or |
| RAW buffers for {@link android.hardware.camera2.DngCreator} can be |
| done with {@link android.media.ImageReader} with the {@link |
| android.graphics.ImageFormat#JPEG} and {@link |
| android.graphics.ImageFormat#RAW_SENSOR} formats. Application-driven |
| processing of camera data in RenderScript, OpenGL ES, or directly in |
| managed or native code is best done through {@link |
| android.renderscript.Allocation} with a YUV {@link |
| android.renderscript.Type}, {@link android.graphics.SurfaceTexture}, |
| and {@link android.media.ImageReader} with a {@link |
| android.graphics.ImageFormat#YUV_420_888} format, respectively.</p> |
| |
| <p>The application then needs to construct a {@link |
| android.hardware.camera2.CaptureRequest}, which defines all the |
| capture parameters needed by a camera device to capture a single |
| image. The request also lists which of the configured output Surfaces |
| should be used as targets for this capture. The CameraDevice has a |
| {@link android.hardware.camera2.CameraDevice#createCaptureRequest |
| factory method} for creating a {@link |
| android.hardware.camera2.CaptureRequest.Builder request builder} for a |
| given use case, which is optimized for the Android device the |
| application is running on.</p> |
| |
| <p>Once the request has been set up, it can be handed to the active |
| capture session either for a one-shot {@link |
| android.hardware.camera2.CameraCaptureSession#capture capture} or for |
| an endlessly {@link |
| android.hardware.camera2.CameraCaptureSession#setRepeatingRequest |
| repeating} use. Both methods also have a variant that accepts a list |
| of requests to use as a burst capture / repeating burst. Repeating |
| requests have a lower priority than captures, so a request submitted |
| through <code>capture()</code> while there's a repeating request |
| configured will be captured before any new instances of the currently |
| repeating (burst) capture will begin capture.</p> |
| |
| <p>After processing a request, the camera device will produce a {@link |
| android.hardware.camera2.TotalCaptureResult} object, which contains |
| information about the state of the camera device at time of capture, |
| and the final settings used. These may vary somewhat from the request, |
| if rounding or resolving contradictory parameters was necessary. The |
| camera device will also send a frame of image data into each of the |
| output {@code Surfaces} included in the request. These are produced |
| asynchronously relative to the output CaptureResult, sometimes |
| substantially later.</p> |
| |
| </BODY> |
| </HTML> |
