Camera2谷歌官方文档（1） 概述

android.hardware.camera2

（一）概述

The android.hardware.camera2 package provides aninterface to individual camera devices connected to an Android device. Itreplaces the deprecatedCamera class.

android.hardware.camera2包为相机设备(camera devices)连接到安卓设备提供了一个接口。 它替代了已弃用的Camera类。

 

This package models a camera device as a pipeline, which takes ininput requests for capturing a single frame, captures the single image per therequest, and then outputs one capture result metadata packet, plus a set ofoutput image buffers for the request. The requests are processed in-order, andmultiple requests can be in flight at once. Since the camera device is apipeline with multiple stages, having multiple requests in flight is requiredto maintain full framerate on most Android devices.

这个包将相机设备看做一个管道，管道接收输入请求，根据请求捕获单帧，捕获单张图片，然后输出一个捕获结果元数据(metadata)包，以及对应请求的一组输出图片缓冲区。请求按顺序进行，并且多个请求可以一次并行。因为相机设备是具有多个阶段的管道，要求在运行中有多个请求来维持大多数Android设备上的全帧速率（这里可能翻译有很大问题）。

 

To enumerate, query, and open available cameradevices, obtain a CameraManager instance.

为了枚举，查询，打开可用的camera devices，首先获得一个CameraManager实例。

获取CameraManager实例的方法：（打开相机前需要调用）

CameraManager manager = (CameraManager) getSystemService(Context.CAMERA_SERVICE);

Individual CameraDevices provide a set of static property informationthat describes the hardware device and the available settings and outputparameters for the device. This information is provided through the CameraCharacteristics object, and is available throughgetCameraCharacteristics(String).

CameraDevices提供了一组静态属性信息，描述硬件设备以及设备的可用设置和输出参数。该信息通过CameraCharacteristics 对象提供，并且通过getCameraCharacteristics(String)获得。

To capture or stream images from a camera device, theapplication must first create a camera capturesession witha 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 sizeand format (if applicable) to match the sizes and formats available from thecamera device. A target Surface can be obtained from a variety of classes,including SurfaceView, SurfaceTexture via Surface(SurfaceTexture), MediaCodec, MediaRecorder, Allocation, andImageReader.

为了从相机设备捕获或者流出（stream）图片，应用程序必须首先创建一个具有一组输出界面的camera capturesession ，以和相机设备一起使用，这需要使用createCaptureSession(List, CameraCaptureSession.StateCallback,Handler)构建。每个界面需要预先配置适当的大小和格式（如果适用）以匹配相机设备可用的大小和格式。目标Surface可通过不同的类获得，包括通过 Surface(SurfaceTexture)创建的SurfaceView, SurfaceTexture ，MediaCodec, MediaRecorder, Allocation,以及ImageReader。

 

Generally, camera preview images are sent to SurfaceView or TextureView (via its SurfaceTexture). Capture of JPEG images or RAW buffers forDngCreator can be done with ImageReader with the JPEG and RAW_SENSOR formats. Application-driven processing of cameradata in RenderScript, OpenGL ES, or directly in managed or native code is bestdone through Allocation with a YUV Type, SurfaceTexture, and ImageReader with a YUV_420_888 format, respectively.

通常来说，相机预览图片被发送至SurfaceView 或者TextureView (通过它的SurfaceTexture)。为DngCreater捕获JPEG图片或者RAW缓冲区可以通过JPEG或者RAW SENSOR形式的 ImageReader获得。RenderScript，OpenGL ES或直接受管，或本地代码中的相机数据的应用驱动的处理最好通过分别使用YUV_420_888格式的YUV类型，SurfaceTexture以及ImageReader进行分配。

 

The application then needs to construct a CaptureRequest, which defines all the capture parameters needed by acamera device to capture a single image. The request also lists which of theconfigured output Surfaces should be used as targets for this capture. TheCameraDevice has a factory method for creating a request builder for a given use case, which is optimized for theAndroid device the application is running on.

然后，应用程序需要构建一个CaptureRequest，它定义了相机设备捕获单个图片所需的所有捕获参数。 该请求还列出了哪些配置的输出表面应该用作此捕获的目标。 CameraDevice拥有一个factory method方法（createCaptureRequest）为每个使用案例创建一个request builder，针对正在运行的Android设备进行了优化。

 

Once the request has been set up, it can be handed tothe active capture session either for a one-shot capture or for an endlessly repeating use. Both methods also have a variant thataccepts a list of requests to use as a burst capture / repeating burst.Repeating requests have a lower priority than captures, so a request submittedthrough capture() while there's a repeating request configured will becaptured before any new instances of the currently repeating (burst) capturewill begin capture.

一旦请求被建立，它可以交给活动捕获会话进行单次捕获或不停地重复使用。 两种方法也有一个变体，它接受一个用作突发捕获/重复突发的请求的列表。 重复请求的优先级低于捕获，因此虽然已经有一个配置的重复请求，通过capture()提交的请求，将在当前重复（burst）请求将开始捕获的任何新实例之前，被捕获。

 

After processing a request, the camera device willproduce a TotalCaptureResult object, which contains information about thestate of the camera device at time of capture, and the final settings used.These may vary somewhat from the request, if rounding or resolvingcontradictory parameters was necessary. The camera device will also send aframe of image data into each of the output Surfaces included in the request. These are producedasynchronously relative to the output CaptureResult, sometimes substantiallylater.

处理请求后，相机设备将产生一个TotalCaptureResult对象，该对象包含有关拍摄时相机设备状态的信息以及使用的最终设置。 如果需要舍入或解决矛盾的参数，这些可能与请求的参数有所不同。 相机设备还将将图像数据帧发送到请求中包括的每个输出表面。 这些相对于输出CaptureResult是异步产生的，有时候稍微延后。

 

（二）相关的类

（1）CameraCaptureSession：A configured capture session for a CameraDevice, used for capturing images from the camera or reprocessing images captured from thecamera in the same session previously.

为CameraDevice配置的捕获会话，用于从相机中捕获图像，或重新处理先前在同一会话中从相机捕获的图像。

（2）CameraCaptureSession.CaptureCallback：A callback object for tracking the progress of aCaptureRequest submitted to the camera device.

一个回调对象，用于跟踪提交给相机设备的CaptureRequest的进度。

（3）CameraCaptureSession.StateCallback：A callback object for receiving updates about thestate of a camera capture session.

用于接收有关camera capture session状态更新的回调对象。

（4）CameraCharacteristics：The properties describing a CameraDevice.

描述一个CameraDevice的属性。

（5）CameraCharacteristics.Key<T>：A Key is used to do camera characteristics fieldlookups with get(CameraCharacteristics.Key).

使用get（CameraCharacteristics.Key）进行相机属性域查找，Key对应着属性。

（6）CameraConstrainedHighSpeedCaptureSession：A constrained high speed capture session for a CameraDevice,used for capturing high speed images from the CameraDevice for high speed video recording use case. 

用于CameraDevice的受限高速捕获会话，用于从CameraDevice捕获用于高速视频录制用例的高速图像。

（7）CameraDevice：The CameraDevice class is a representation of a singlecamera connected to an Android device, allowing for fine-grain control of imagecapture and post-processing at high frame rates. 

CameraDevice类是连接到Android设备的单个相机的表示，允许以高帧速率进行图像捕获和后处理的细粒度控制（fine-grain control）。

（8）CameraDevice.StateCallback：A callback objects for receiving updates about thestate of a camera device.

用于接收有关摄像机设备状态的更新的回调对象。

（9）CameraManager：A system service manager for detecting,characterizing, and connecting to CameraDevices.

用于检测，表征和连接到CameraDevices的系统服务管理器。

（10）CameraManager.AvailabilityCallback：A callback for camera devices becoming available orunavailable to open.

相机设备可用或者无法打开的回调。

（11）CameraManager.TorchCallback：A callback for camera flash torch modes becomingunavailable, disabled, or enabled.

相机闪光灯模式变为不可获得，禁用或启用的回调。

（12）CameraMetadata<TKey>：The base class for camera controls and information.

相机控制和信息的基础类。

（13）CaptureFailure：A report of failed capture for a single image capturefrom the image sensor.

从图像传感器捕获单个图像的失败捕获报告。

（14）CaptureRequest：An immutable package of settings and outputs needed tocapture a single image from the camera device.

从相机设备捕获单图所需的不可变得设置和输出包。

（15）CaptureRequest.Builder：A builder for capture requests.

捕获请求的构建器。

（16）CaptureRequest.Key<T>：A Key is used to do capture request field lookups withget(CaptureResult.Key) or to set fields with set(Key, Object).

使用get(CaptureResult.Key)可查询和Key对应的捕获请求区域，或者使用set(Key, Object)设置区域。

（17）CaptureResult：The subset of the results of a single image capturefrom the image sensor.

从图像传感器捕获单图结果的子集。

（18）CaptureResult.Key<T>：A Key is used to do capture result field lookups withget(CaptureResult.Key).

使用get(CaptureResult.Key)可查询和Key相关的捕获结果区域。

（19）DngCreator：The DngCreator class provides functions to write rawpixel data as a DNG file.

DngCreator类提供将raw像素数据写入DNG文件的功能。

（20）TotalCaptureResult：The total assembled results of a single image capturefrom the image sensor.

来自图像传感器的单个图像捕获的总体组合结果。

Exceptions

CameraAccessException：CameraAccessException is thrown if a camera devicecould not be queried or opened by the CameraManager, or if the connection to anopened CameraDevice is no longer valid.

如果CameraManager无法查询或打开相机设备，或者与打开的CameraDevice的连接不再有效，则会引发CameraAccessException异常。