| Eino-Ville Talvala | b267554 | 2012-12-12 13:29:45 -0800 | [diff] [blame] | 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.photography 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.photography.CameraManager} instance.</p> |
| 32 | |
| 33 | <p>Individual {@link android.hardware.photography.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.photography.CameraProperties} object.</p> |
| 38 | |
| 39 | <p>To capture or stream images from a camera device, the application |
| 40 | must first configure a set of output Surfaces for use with the camera |
| 41 | device, with {@link |
| 42 | android.hardware.photography.CameraDevice#configureOutputs}. Each |
| 43 | Surface has to be pre-configured with an appropriate size and format |
| 44 | (if applicable) to match the sizes and formats available from the |
| 45 | camera device. A target Surface can be obtained from a variety of |
| 46 | classes, including {@link android.view.SurfaceView}, {@link |
| 47 | android.graphics.SurfaceTexture} via {@link |
| 48 | android.view.Surface#Surface(SurfaceTexture), {@link |
| 49 | android.media.MediaCodec}, and {@link android.media.ImageReader}. |
| 50 | </p> |
| 51 | |
| 52 | <p>The application then needs to construct a {@link |
| 53 | android.hardware.photography.CaptureRequest}, which defines all the |
| 54 | capture parameters needed by a camera device to capture a single |
| 55 | image. The request also lists which of the configured output Surfaces |
| 56 | should be used as targets for this capture. The CameraDevice has a |
| 57 | {@link android.hardware.photography.CameraDevice#createCaptureRequest |
| 58 | convenience factory method} for creating a request for a given use |
| 59 | case which is optimized for the Android device the application is |
| 60 | running on.</p> |
| 61 | |
| 62 | <p>Once the request has been set up, it can be handed to the |
| 63 | CameraDevice either for a one-shot {@link |
| 64 | android.hardware.photography.CameraDevice#capture} or for an endlessly |
| 65 | {@link android.hardware.photography.CameraDevice#setRepeatingRequest |
| 66 | repeating} use. Both methods also accept a list of requests to use as |
| 67 | a burst capture / repeating burst. Repeating requests have a lower |
| 68 | priority than captures, so a request submitted |
| 69 | through <code>capture()</code> while there's a repeating request |
| 70 | configured will be captured as soon as the current repeat (burst) |
| 71 | capture completes.</p> |
| 72 | |
| 73 | <p>After processing a request, the camera device will produce a {@link |
| 74 | android.hardware.photography.CaptureResult} object, which contains |
| 75 | information about the state of the camera device at time of capture, |
| 76 | and the final settings used. These may vary somewhat from the request, |
| 77 | if rounding or resolving contradictory parameters was necessary. The |
| 78 | camera device will also send a frame of image data into each of the |
| 79 | output streams included in the request. These are produced |
| 80 | asynchronously relative to the output CaptureResult, sometimes |
| 81 | substantially later.</p> |
| 82 | |
| 83 | </BODY> |
| 84 | </HTML> |