Android camera: android.hardware.camera2 package

frameworks/base/core/java/android/hardware/camera2/CameraManager.java


android.hardware.camera2包为每个连接到android device的camera device提供一个接口;
android.hardware.camera2用于取代android.hardware.Camera
The android.hardware.camera2 package provides an interface to
individual camera devices connected to an Android device. It replaces
the deprecated android.hardware.Camera class.


android.hardware.camera2把camera device建模为管道，该管道接收捕捉一帧的请求，然后输出捕捉结果metadata packet和一组输出图像buffer.
请求按顺序处理且多个请求可一次性处理。因为camera device管道包括多个阶段？？
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.


为了枚举、查询、打开可用的camera devices, 需要获得一个android.hardware.camera2.CameraManager实例。
To enumerate, query, and open available camera devices, obtain a
android.hardware.camera2.CameraManager instance.


每个android.hardware.camera2.CameraDevice提供一系列的属性，该属性通过
android.hardware.camera2.CameraManager#getCameraCharacteristics函数获得。
Individual android.hardware.camera2.CameraDevice
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
android.hardware.camera2.CameraCharacteristics object, and is
available through android.hardware.camera2.CameraManager#getCameraCharacteristics


为了从camera device捕捉图像，app必须创建一个回话：Capture　Session，该回话需要一组输出surface用于camera device.
该功能通过调用函数android.hardware.camera2.CameraDevice#createCaptureSession实现。
To capture or stream images from a camera device, the application
must first create a android.hardware.camera2.CameraCaptureSession camera capture session
with a set of output Surfaces for use with the camera device, with
android.hardware.camera2.CameraDevice#createCaptureSession. 


根据camera device支持的大小和格式通过函数android.hardware.camera2.params.StreamConfigurationMap配置surface.
surface可通过下面的函数获得。
Each Surface has to be pre-configured with an 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}.




Generally, camera preview images are sent to {android.view.SurfaceView} or {android.view.TextureView} (via its
{android.graphics.SurfaceTexture}). 
Capture of JPEG images or
RAW buffers for {android.hardware.camera2.DngCreator} can be
done with {android.media.ImageReader} with the {
android.graphics.ImageFormat#JPEG} and {
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 {
android.renderscript.Allocation} with a YUV {
android.renderscript.Type}, {android.graphics.SurfaceTexture},
and {android.media.ImageReader} with a {
android.graphics.ImageFormat#YUV_420_888} format, respectively.






The application then needs to construct a {
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
{android.hardware.camera2.CameraDevice#createCaptureRequest
factory method} for creating a {
android.hardware.camera2.CaptureRequest.Builder request builder} for a
given use case, which is optimized for the Android device the
application is running on.




一旦请求构建后，该请求调用函数进行处理：one-shot(android.hardware.camera2.CameraCaptureSession#capture)
或者repeating(android.hardware.camera2.CameraCaptureSession#setRepeatingRequest).
Once the request has been set up, it can be handed to the active
capture session either for a one-shot {
android.hardware.camera2.CameraCaptureSession#capture capture} or for
an endlessly {
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.


请求处理后，camera device会生成一个android.hardware.camera2.TotalCaptureResult对象，
该对象包含捕捉时camera device的状态和设置；camera device也会发送image数据到输出surface.
数据的发送和输出CaptureResult是异步的。
After processing a request, the camera device will produce a {
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 {Surfaces} included in the request. These are produced
asynchronously relative to the output CaptureResult, sometimes
substantially later.