Camera2 doc

The android.hardware.camera2 package provides an interface to individual camera devices connected to an Android device. It replaces the deprecated Camera class.
android.hardware.camera2包提供一個連接到Android設備的獨立Camera設備接口


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.
這個包把相機設備模擬成一個流水線(管道?), 這個流水線可以接受拍攝單個frame的輸入請求， 可以爲每一個請求拍攝一個圖片， 然後輸出一個拍攝結果元數據包， 附帶所請求的輸出圖片buffers集合。
這些請求被順序處理，並且多個請求可以同時被髮出。 由於相機設備室一個多狀態的流水線， 爲了在大多數安卓設備上保持全幀率， 同時發出多個請求成爲必須.


To enumerate, query, and open available camera devices, obtain a CameraManager instance.
爲了列舉，查詢，和打開可用的相機設備，需要獲取一個CameraManager實例。


Individual 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 CameraCharacteristics object, and is available through getCameraCharacteristics(String)
獨立的CameraDevices提供一個描述硬件設備&可用設置&輸出參數的靜態的屬性信息集合。這些信息通過CameraCharacteristics類提供，可以通過getCameraCharacteristics(String)調用。


To capture or stream images from a camera device, the application must first create a camera capture session with a set of output Surfaces for use with the camera device, with createCaptureSession(List, CameraCaptureSession.StateCallback, Handler). Each Surface has to be pre-configured with an 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 SurfaceView, SurfaceTexture via Surface(SurfaceTexture), MediaCodec, MediaRecorder, Allocation, and ImageReader.
想從一個相機設備拍照或獲取數據流，應用需要首先創建一個帶有供camera device使用的surfaces集合的camera capture session， 如此：createCaptureSession(List, CameraCaptureSession.StateCallback, Handler). 每一個surface必須提前配置好和相機設備相對於的大小和格式。
一個目標surface可以從幾個類獲得， 比如SurfaceView， SurfaceTexture via Surface， MediaCodec， MediaRecorder， Allocation， 和 ImageReader。


Generally, camera preview images are sent to SurfaceView or TextureView (via its SurfaceTexture). Capture of JPEG images or RAW buffers for DngCreator can be done with ImageReader with the JPEG and RAW_SENSOR formats. Application-driven processing of camera data in RenderScript, OpenGL ES, or directly in managed or native code is best done through Allocation with a YUV Type, SurfaceTexture, and ImageReader with a YUV_420_888 format, respectively.
一般來說，相機預覽圖片被髮送到SurfaceView或TextureView(通過它的SurfaceTexture)。通過JPEG和RAW_SENSOR的ImageReader可以完成JPEG和DngCreater的RAW buffers的拍照。
程序驅動的數據處理可以通過分別分配YUV type， SurfaceTexture， 和YUV_420_888格式的ImageReader使在RenderScript， OpenGL ES， 或直接管理或native code得到很好的處理。


The application then needs to construct a 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 factory method for creating a request builder for a given use case, which is optimized for the Android device the application is running on.
應用程序然後需要創建一個CaptureRequest，CaptureRequest定義了設備拍攝一張照片需要的所有拍攝參數。
此request還列出了作爲此次拍照的tartgets的配置好的output surfaces。
CameraDevice類有一個爲一個用戶case創建一個request builder的工廠方法，此方法已經針對程序運行的Android設備優化。




Once the request has been set up, it can be handed to the active capture session either for a one-shot capture or for an endlessly 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 capture() while there's a repeating request configured will be captured before any new instances of the currently repeating (burst) capture will begin capture.
一旦這些請求被髮送， 它們可以被激活的capture session作爲one-shot capture或者無限循環處理。
這兩個方法也都有一個變量可以接受作爲burst/重複burst的請求list。
Repeating requests比captures優先級低，所以當repeating request正在執行時來了一個capture() request，這個capture會先執行，然後再執行repeating的下一個拍照實例。




After processing a request, the camera device will produce a 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.
處理完一個request後， camera device會生成一個TotalCaptureResult對象， 包含了拍照時設備的狀態信息和所用的配置。
這些設置根據request變化，如果解決對立參數必要的話。 
相機設備還會給request裏的每一個output surfaces發送圖片數據。
這些數據和captureResult是異步的，稍微晚一點。