Android Camera2 API 学习

Developer Camera API (https://developer.android.google.cn/reference/android/hardware/camera2/package-summary)

1. CameraManager

一种系统服务管理器，用于检测、描述和连接到照相机设备。
java CameraManager mCameraManager = (CameraManager) getSystemService(Context.CAMERA_SERVICE);

内部类

类名	作用
CameraManager.AvailabilityCallback	监听相机是否可用的回调
CameraManager.TorchCallback	监听闪光灯状态的回调

CameraManager.AvailabilityCallback

一个用于相机设备的回调或无法打开的回调。
当相机未被使用或者一个可以拆卸的相机连接时，camera变得可用。
当一个应用或者服务使用相机，或者可拆卸相机断开时，camera变得不可用

方法名	解释
onCameraAvailable(String cameraId)	一个新的相机变得可用
onCameraUnavailable(String cameraId)	前一个可用的相机变为不可用

CameraManager.TorchCallback

一个关于闪光灯变得不可用、已禁用和已启用的回调
不可用：所属的相机设备变得不可用或者有其他更高优先级的相机行为导致相机资源比较繁忙
已禁用：闪光灯被关闭或者所属的相机设备不再使用并且其他相机资源不再繁忙
已启用：通过 CameraManager.setTorchMode(String, boolean) 打开闪光灯
只有当闪光灯模式为 disabled和enabled时，才可以通过CameraManager.setTorchMode(String, boolean)设置闪光灯模式

方法名	解释
onTorchModeChanged(String cameraId, boolean enabled)	闪光灯模式被设置为enabled 或者 disabled并且可以通过CameraManager.setTorchMode(String, boolean)改变
onTorchModeUnavailable(String cameraId)	闪光灯模式已无法通过 CameraManager.setTorchMode(String, boolean) 设置

方法

返回值	方法名	解释
CameraCharacteristics	getCameraCharacteristics(String cameraId)	查询摄像头为 cameraId 的支持的功能
String[]	getCameraIdList()	获取当前设备可连接的所有摄像头的 cameraId
void	openCamera(String cameraId, CameraDevice.StateCallback callback, Handler handler)	在Handler(可以为null，null表示在主线程)线程打开cameraId相机
void	openCamera(String cameraId, Executor executor, CameraDevice.StateCallback callback)	通过executor打开cameraId
void	registerAvailabilityCallback(Executor executor, CameraManager.AvailabilityCallback callback)	注册一个回调来获取camera设备的可用性
void	registerAvailabilityCallback(CameraManager.AvailabilityCallback callback, Handler handler)	同上（通过executor和handler注册回调的不同场景以及各自的优势还不清楚）
void	registerTorchCallback(CameraManager.TorchCallback callback, Handler handler)	注册一个回调来获取闪光灯状态
void	registerTorchCallback(Executor executor, CameraManager.TorchCallback callback)	同上
void	setTorchMode(String cameraId, boolean enabled)	在不打开相机设备的情况下，设置闪光灯的闪光灯模式
void	unregisterAvailabilityCallback(CameraManager.AvailabilityCallback callback)	删除之前添加的回调
void	unregisterTorchCallback(CameraManager.TorchCallback callback)	删除之前添加的回调，回调将不再接收torch mode状态回调

2. CameraDevice

CameraDevice类是连接到Android设备的单个摄像头的表示，允许以高帧速率对图像捕获和后处理进行细粒度控制。

你的应用程序必须在manifest 中声明相机权限才可以使用相机

一个相机设备也许支持定义在 CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL 几种级别中的一个。
如果相机支持 CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY 级别，那么该相机是向后兼容的并且仅最小程度的支持camera2 API。
如果相机支持 CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED 级别，功能集与Camera API相同，但是接口更加清晰和高效。
如果相机支持 CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL 级别，则该设备是可移动摄像头，其提供与 CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED 级别相似但略少的功能。
如果相机支持 CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_FULL 或 CameraMetadata#INFO_SUPPORTED_HARDWARE_LEVEL_3 级别，该相机相对旧版 Camera API 提供了更多的功能。
如果应用程序需要一个全级别支持的操作,需要在manifest中声明“android.hardware.camera.level.full”。

内部类

类名	作用
CameraDevice.StateCallback	相机更新状态的回调

CameraDevice.StateCallback

一个接收相机更新状态的回调。
必须先通过 CameraManager#openCamera 方法打开相机设备，才能使用该回调。
这些状态更新包括有关设备完成启动（允许调用 CameraDevice.createCaptureSession(SessionConfiguration)），设备断开或关闭以及有关意外设备错误的通知。
有关特定 CaptureRequest 进程的事件是通过 CameraCaptureSession.CaptureCallback 提供的 CameraCaptureSession#capture, CameraCaptureSession#captureBurst, CameraCaptureSession#setRepeatingRequest, or CameraCaptureSession#setRepeatingBurst 方法

详情看该方法的调用
CameraManager.openCamera(String, CameraDevice.StateCallback, Handler)

常量：

类型	常量名	解释
int	ERROR_CAMERA_DEVICE	onError(CameraDevice, int)报告的错误代码，表示摄像头设备遇到了致命错误
int	ERROR_CAMERA_DISABLED	onError(CameraDevice, int)报告的错误代码，表示由于设备策略而无法打开摄像头设备
int	ERROR_CAMERA_IN_USE	onError(CameraDevice, int)报告的错误代码，表示摄像头设备已经在使用中
int	ERROR_CAMERA_SERVICE	onError(CameraDevice, int)报告的错误代码，表示摄像头服务遇到了致命错误
int	ERROR_MAX_CAMERAS_IN_USE	onError(CameraDevice, int)报告的错误代码，因为打开了太多其他摄像头设备导致无法打开该设备

方法：

方法名	解释
onClosed(CameraDevice camera)	当相机调用 CameraDevice#close时，该方法会回调
onDisconnected(CameraDevice camera)	当相机不在可用时
onError(CameraDevice camera, int error)	当相机设备遇到严重问题时
onOpened(CameraDevice camera)	当相机完成打开操作后

常量

类型	常量名	解释
int	TEMPLATE_MANUAL	应用直接控制照片参数的基础模板
int	TEMPLATE_PREVIEW	创建一个适合相机预览窗口的请求
int	TEMPLATE_RECORD	创建一个适合视频录制的请求
int	TEMPLATE_STILL_CAPTURE	创建适合静态图像捕获的请求
int	TEMPLATE_VIDEO_SNAPSHOT	创建视频录制时捕获静态图片的请求
int	TEMPLATE_ZERO_SHUTTER_LAG	创建适用于零快门延迟的请求

以上常量可以通过 CameraDevice#createCaptureRequest(int)方法设置

方法

返回值	方法名	解释
void	close()	尽可能快的关闭与相机设备的连接
CaptureRequest.Builder	createCaptureRequest(int templateType, Set physicalCameraIdSet)	为新的捕获请求创建CaptureRequest.Builder，使用模板初始化目标用例
CaptureRequest.Builder	createCaptureRequest(int templateType)	同上
void	createCaptureSession(SessionConfiguration config)	使用SessionConfiguration帮助程序对象创建新的CameraCaptureSession，该对象聚合所有支持的参数
void	createCaptureSession(List outputs, CameraCaptureSession.StateCallback callback, Handler handler)	通过向camera device提供目标Surfaces的方式创建会话
void	createCaptureSessionByOutputConfigurations(List outputConfigurations, CameraCaptureSession.StateCallback callback, Handler handler)	通过向camera device提供目标Surfaces和其相关配置的方式创建会话
void	createConstrainedHighSpeedCaptureSession(List outputs, CameraCaptureSession.StateCallback callback, Handler handler)	创建一个受限的高速捕捉会话
CaptureRequest.Builder	createReprocessCaptureRequest(TotalCaptureResult inputResult)	创建CaptureRequest.Builder通过TotalCaptureResult重新处理CaptureRequest
void	createReprocessableCaptureSession(InputConfiguration inputConfig, List outputs, CameraCaptureSession.StateCallback callback, Handler handler)	通过提供可重新处理的Surface配置和目标Surfaces给camera device创建新的可重新处理的会话
void	createReprocessableCaptureSessionByConfigurations(InputConfiguration inputConfig, List outputs, CameraCaptureSession.StateCallback callback, Handler handler)	通过提供可重新处理的输入配置和 OutputConfiguration 给camera device创建新的可重新处理的会话
String	getId()	获得相机设备的id
boolean	isSessionConfigurationSupported(SessionConfiguration sessionConfig)	检查摄像机设备是否支持特定的SessionConfiguration

3. CameraCaptureSession

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

CameraCaptureSession是通过向CameraDevice#creationCaptureSession提供一组目标输出表面，或者为CameraDevice#createReprocessableCaptureSession提供一个InputConfiguration和一组目标输出表面来创建的，以便进行可重新处理的捕获会话。 创建后，会话处于活动状态，直到摄像机设备创建新会话或关闭摄像机设备。

所有捕获会话都可用于从摄像机捕获图像，但只有可重新处理的捕获会话可以重新处理先前在同一会话中从摄像机捕获的图像。

创建会话是一项代价比较高的操作，可能需要几百毫秒，因为它需要配置摄像机设备的内部管道并分配内存缓冲区以将图像发送到所需目标。 因此，设置是异步完成的，CameraDevice#createCaptureSession和CameraDevice#createReprocessableCaptureSession会将现成的CameraCaptureSession发送到提供的监听器的CameraCaptureSession.StateCallback#onConfigured回调。 如果无法完成配置，则调用CameraCaptureSession.StateCallback#onConfigureFailed，并且会话不会被激活。

如果摄像机设备创建了新会话，则会关闭先前的会话，并将调用其关联的StateCallback#onClosed回调。 如果在会话关闭后调用，则所有会话方法都将抛出 IllegalStateException。

关闭会话会清除所有重复请求（就像调用了stopRepeating() 一样），但在新创建的会话接管并重新配置摄像机设备之前，仍将正常完成所有正在进行的捕获请求。

内部类

类名	作用
CameraCaptureSession.CaptureCallback	用于跟踪提交给照相机设备的CaptureRequest的进度的回调对象
CameraCaptureSession.StateCallback	用于接收有关相机捕获会话状态的更新的回调对象

CameraCaptureSession.CaptureCallback

用于跟踪提交给照相机设备的CaptureRequest的进度的回调对象
当触发捕获开始以及捕获完成时，将调用此回调。 如果捕获图像时出错，则会触发错误方法而不是完成方法。

方法：

方法名	解释
onCaptureBufferLost(CameraCaptureSession session, CaptureRequest request, Surface target, long frameNumber)	如果无法将捕获的单个缓冲区发送到其目标surface，则调用此方法。
onCaptureCompleted(CameraCaptureSession session, CaptureRequest request, TotalCaptureResult result)	当图像捕获完全完成且所有结果的 metadata 都可用时，将调用此方法。
onCaptureFailed(CameraCaptureSession session, CaptureRequest request, CaptureFailure failure)	当摄像机设备无法为请求生成CaptureResult时
onCaptureProgressed(CameraCaptureSession session, CaptureRequest request, CaptureResult partialResult)	当图像捕获取得部分进展时，调用此方法; 可以获得图像捕获的一些（但不是全部）结果。
onCaptureSequenceAborted(CameraCaptureSession session, int sequenceId)	在CaptureCallback中独立于其他方法调用此方法，此时捕获序列在通过此侦听器返回任何CaptureResult或CaptureFailure之前中止。
onCaptureSequenceCompleted(CameraCaptureSession session, int sequenceId, long frameNumber)	当捕获序列完成并且已经通过此侦听器返回所有CaptureResult或CaptureFailure时，此方法在CaptureCallback中独立调用。
onCaptureStarted(CameraCaptureSession session, CaptureRequest request, long timestamp, long frameNumber)	当相机设备已经开始捕获请求的输出图像，在图像曝光开始时，或者当相机设备已经开始处理用于再处理请求的输入图像时，调用该方法。

CameraCaptureSession.StateCallback

用于接收有关相机捕获会话状态的更新的回调对象。

方法：

方法名	解释
onActive(CameraCaptureSession session)	当会话开始主动处理捕获请求时，将调用此方法。
onCaptureQueueEmpty(CameraCaptureSession session)	当摄像机设备的输入捕获队列变空并准备接受下一个请求时，将调用此方法。
onClosed(CameraCaptureSession session)	会话关闭时调用此方法。
onConfigureFailed(CameraCaptureSession session)	如果无法将会话按照请求配置，则调用此方法
onConfigured(CameraCaptureSession session)	当摄像机设备完成自身配置时，将调用此方法，并且会话可以开始处理捕获请求。
onReady(CameraCaptureSession session)	每当会话不再有要处理的捕获请求时，都会调用此方法。
onSurfacePrepared(CameraCaptureSession session, Surface surface)	当输出Surface的缓冲区预分配完成时，将调用此方法

方法

返回值	方法名	解释
void	abortCaptures()	尽可能快地丢弃当前待处理和正在进行的所有捕获。
int	capture(CaptureRequest request, CameraCaptureSession.CaptureCallback listener, Handler handler)	提交一个图像请求，以便被摄像机设备捕捉到。
int	captureBurst(List requests, CameraCaptureSession.CaptureCallback listener, Handler handler)	提交一份请求列表，按顺序以突发方式捕获请求。
int	captureBurstRequests(List requests, Executor executor, CameraCaptureSession.CaptureCallback listener)	提交一份请求列表，按顺序以突发方式捕获请求。
int	captureSingleRequest(CaptureRequest request, Executor executor, CameraCaptureSession.CaptureCallback listener)	提交要由相机设备捕获的图像的请求。
void	close()	异步关闭此捕获会话。
void	finalizeOutputConfigurations(List outputConfigs)	最后确定输出配置，这些配置包含了延迟和或额外Surfaces的输出配置。
CameraDevice	getDevice()	获取为此会话创建的摄像头设备。
Surface	getInputSurface()	获取与可重新处理的捕获会话关联的输入Surface。
boolean	isReprocessable()	如果应用程序可以使用此摄像头捕获会话提交重新处理捕获请求，则返回
void	prepare(Surface surface)	为输出Surface预分配所有缓冲区。
int	setRepeatingBurst(List requests, CameraCaptureSession.CaptureCallback listener, Handler handler)	这个捕获会话请求不断地重复捕获一系列图像。
int	setRepeatingBurstRequests(List requests, Executor executor, CameraCaptureSession.CaptureCallback listener)	同上
int	setRepeatingRequest(CaptureRequest request, CameraCaptureSession.CaptureCallback listener, Handler handler)	这个捕获会话请求不断地重复捕获单个图像。
int	setSingleRepeatingRequest(CaptureRequest request, Executor executor, CameraCaptureSession.CaptureCallback listener)	同上
void	stopRepeating()	取消请求
void	updateOutputConfiguration(OutputConfiguration config)	配置完成后更新OutputConfiguration