blob: c61998403c8ee536b559f6ed73581426a091e48b [file] [log] [blame]
  1. <!-- Copyright (C) 2013 The Android Open Source Project
  2. Licensed under the Apache License, Version 2.0 (the "License");
  3. you may not use this file except in compliance with the License.
  4. You may obtain a copy of the License at
  6. Unless required by applicable law or agreed to in writing, software
  7. distributed under the License is distributed on an "AS IS" BASIS,
  8. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  9. See the License for the specific language governing permissions and
  10. limitations under the License.
  11. -->
  12. <HTML>
  13. <BODY>
  14. <p>The android.hardware.camera2 package provides an interface to
  15. individual camera devices connected to an Android device. It replaces
  16. the deprecated {@link android.hardware.Camera} class.</p>
  17. <p>This package models a camera device as a pipeline, which takes in
  18. input requests for capturing a single frame, captures the single image
  19. per the request, and then outputs one capture result metadata packet,
  20. plus a set of output image buffers for the request. The requests are
  21. processed in-order, and multiple requests can be in flight at
  22. once. Since the camera device is a pipeline with multiple stages,
  23. having multiple requests in flight is required to maintain full
  24. framerate on most Android devices.</p>
  25. <p>To enumerate, query, and open available camera devices, obtain a
  26. {@link android.hardware.camera2.CameraManager} instance.</p>
  27. <p>Individual {@link android.hardware.camera2.CameraDevice
  28. CameraDevices} provide a set of static property information that
  29. describes the hardware device and the available settings and output
  30. parameters for the device. This information is provided through the
  31. {@link android.hardware.camera2.CameraCharacteristics} object.</p>
  32. <p>To capture or stream images from a camera device, the application
  33. must first configure a set of output Surfaces for use with the camera
  34. device, with {@link
  35. android.hardware.camera2.CameraDevice#configureOutputs}. Each
  36. Surface has to be pre-configured with an appropriate size and format
  37. (if applicable) to match the sizes and formats available from the
  38. camera device. A target Surface can be obtained from a variety of
  39. classes, including {@link android.view.SurfaceView}, {@link
  40.} via {@link
  41. android.view.Surface#Surface(SurfaceTexture), {@link
  42.}, and {@link}.
  43. </p>
  44. <p>The application then needs to construct a {@link
  45. android.hardware.camera2.CaptureRequest}, which defines all the
  46. capture parameters needed by a camera device to capture a single
  47. image. The request also lists which of the configured output Surfaces
  48. should be used as targets for this capture. The CameraDevice has a
  49. {@link android.hardware.camera2.CameraDevice#createCaptureRequest
  50. convenience factory method} for creating a request for a given use
  51. case which is optimized for the Android device the application is
  52. running on.</p>
  53. <p>Once the request has been set up, it can be handed to the
  54. CameraDevice either for a one-shot {@link
  55. android.hardware.camera2.CameraDevice#capture} or for an endlessly
  56. {@link android.hardware.camera2.CameraDevice#setRepeatingRequest
  57. repeating} use. Both methods also accept a list of requests to use as
  58. a burst capture / repeating burst. Repeating requests have a lower
  59. priority than captures, so a request submitted
  60. through <code>capture()</code> while there's a repeating request
  61. configured will be captured as soon as the current repeat (burst)
  62. capture completes.</p>
  63. <p>After processing a request, the camera device will produce a {@link
  64. android.hardware.camera2.CaptureResult} object, which contains
  65. information about the state of the camera device at time of capture,
  66. and the final settings used. These may vary somewhat from the request,
  67. if rounding or resolving contradictory parameters was necessary. The
  68. camera device will also send a frame of image data into each of the
  69. output streams included in the request. These are produced
  70. asynchronously relative to the output CaptureResult, sometimes
  71. substantially later.</p>
  72. {@hide}
  73. </BODY>
  74. </HTML>