Android Camera2 CameraCharacteristics Key 详细解说

一、简介

CameraCharacteristics 是专门用来描述相机设备属性的一个类，继承自CameraMetadata类。给对给定的相机，它里面所包含的属性都是 固定的 ,也就是我们说的静态metadata.
包括：曝光补偿（Exposure compensation）
自动曝光/自动对焦/自动白平衡模式（AE / AF / AWB mode）
自动曝光/自动白平衡锁（AE / AWB lock）
自动对焦触发器（AF trigger）
拍摄前自动曝光触发器（Precapture AE trigger）
测量区域（Metering regions）
闪光灯触发器（Flash trigger）
曝光时间（Exposure time）
感光度（ISO Sensitivity）
帧间隔（Frame duration）
镜头对焦距离（Lens focus distance）
色彩校正矩阵（Color correction matrix）
JPEG 元数据（JPEG metadata）
色调映射曲线（Tonemap curve）
裁剪区域（Crop region）
目标 FPS 范围（Target FPS range）
拍摄意图（Capture intent）
硬件视频防抖（Video stabilization）等。
除了以上的这些，驱动也可以配置特定的KEY，我们可以通过定义一个

    public static final CameraCharacteristics.Key<Integer> keyName =
            new CameraCharacteristics.Key<Integer>("android.counstom.key", Integer.class);
            // 获取指定摄像头的特性
            CameraCharacteristics characteristics
                    = manager.getCameraCharacteristics(mCameraId);
            // 获取驱动自定义的配置属性
            int map = characteristics.get(keyName);

官方文档链接：https://developer.android.google.cn/reference/android/hardware/camera2/CameraCharacteristics

二、获取 CameraCharacteristics 示例

通过CameraManager的getCameraCharacteristics(String cameraId)方法获取指定相机设备的 CameraCharacteristics 对象。

private int mCameraId = CameraCharacteristics.LENS_FACING_FRONT; // 要打开的摄像头ID
private CameraManager mCameraManager; // 相机管理者
private CameraCharacteristics mCameraCharacteristics; // 相机属性

public void openCamera() {
    try {
        mCameraCharacteristics = mCameraManager.getCameraCharacteristics(Integer.toString(mCameraId));
        StreamConfigurationMap map = mCameraCharacteristics.get(CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP);
        // ...省略
    } catch (CameraAccessException e) {
        e.printStackTrace();
    }
}

三、内部类

包含一个CameraCharacteristics.Key的内部类，用做相机特性的字段查询使用。
常搭配CameraCharacteristics.get(CameraCharacteristics.Key key)方法使用。

四、常用方法

1. T get(CameraCharacteristics.Key key)
   获取相机属性中对应字段的值。如果输入的 key 没有设置，将返回 null。

2. List<CameraCharacteristics.Key<?>> getKeys()
   获取该相机设备支持的CameraCharacteristics.Key的列表。
   该方法获取的 Key 的列表，可以保证用作 CameraCharacteristics 类的 get() 方法时不会返回 null。
   返回的 list 是不允许修改的，否则将抛出 UnsupportedOperationException 异常。

3. List<CaptureRequest.Key<?>> getAvailableCaptureRequestKeys()
   获取该相机设备支持的CaptureRequest.Key的列表。可用于 CaptureRequest 类的 get() 方法。

4. List<CaptureResult.Key<?>> getAvailableCaptureResultKeys()
   获取该相机设备支持的CaptureResult.Key的列表。可用于 CaptureResult 类的 get() 方法。

五、成员字段

以下就是一些通用的KEY值及详解

类型	字段名	详解
public static final Key<int[]>	COLOR_CORRECTION_AVAILABLE_ABERRATION_MODES	相机设备支持的像差校正模式列表，用于 android.colorCorrection.aberrationMode
public static final Key<int[]>	CONTROL_AE_AVAILABLE_ANTIBANDING_MODES	相机设备支持的自动曝光反冲带模式列表，用于 android.control.aeAntibandingMode
public static final Key<int[]>	CONTROL_AE_AVAILABLE_MODES	相机设备支持的自动曝光模式列表，用于 android.control.aeMode
public static final Key<Range[]>	CONTROL_AE_AVAILABLE_TARGET_FPS_RANGES	相机设备支持的帧率范围，用于 android.control.aeTargetFpsRange
public static final Key<Range>	CONTROL_AE_COMPENSATION_RANGE	相机设备支持的曝光补偿范围，用于 android.control.aeExposureCompensation
public static final Key	CONTROL_AE_COMPENSATION_STEP	曝光补偿能够改变的最小步长
public static final Key	CONTROL_AE_LOCK_AVAILABLE	相机设备是否支持 android.control.aeLock
public static final Key<int[]>	CONTROL_AF_AVAILABLE_MODES	相机设备支持的自动聚焦模式列表，用于 android.control.afMode
public static final Key<int[]>	CONTROL_AVAILABLE_EFFECTS	相机设备支持的颜色效果列表，用于 android.control.effectMode
public static final Key<int[]>	CONTROL_AVAILABLE_MODES	相机设备支持的控制模式列表，用于 android.control.mode
public static final Key<int[]>	CONTROL_AVAILABLE_SCENE_MODES	相机设备支持的场景模式列表（如夜景、美食、烛光等），用于 android.control.sceneMode
public static final Key<int[]>	CONTROL_AVAILABLE_VIDEO_STABILIZATION_MODES	相机设备支持的视频稳定模式列表，用于 android.control.videoStabilizationMode
public static final Key<int[]>	CONTROL_AWB_AVAILABLE_MODES	相机设备支持的自动白平衡模式列表，用于 android.control.awbMode
public static final Key	CONTROL_AWB_LOCK_AVAILABLE	相机设备是否支持 android.control.awbLock
public static final Key	CONTROL_MAX_REGIONS_AE	自动曝光可使用的最大测量区域数
public static final Key	CONTROL_MAX_REGIONS_AF	自动聚焦可使用的最大测量区域数
public static final Key	CONTROL_MAX_REGIONS_AWB	自动白平衡可使用的最大测量区域数
public static final Key<Range>	CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE	相机设备支持的 boost 范围，用于 android.control.postRawSensitivityBoost
public static final Key	DEPTH_DEPTH_IS_EXCLUSIVE	指出一个捕捉请求是否能够同时支持深度输出（如 DEPTH16 / DEPTH_POINT_CLOUD）和普通颜色输出（如 YUV_420_888, JPEG 或 RAW）
public static final Key<int[]>	DISTORTION_CORRECTION_AVAILABLE_MODES	相机设备支持的畸变矫正模式列表，用于 android.distortionCorrection.mode
public static final Key<int[]>	EDGE_AVAILABLE_EDGE_MODES	相机设备支持的边缘增强模式列表，用于 android.edge.mode
public static final Key	FLASH_INFO_AVAILABLE	相机设备是否有闪光灯部件
public static final Key<int[]>	HOT_PIXEL_AVAILABLE_HOT_PIXEL_MODES	相机设备支持的像素矫正模式列表，用于 android.hotPixel.mode
public static final Key	INFO_SUPPORTED_HARDWARE_LEVEL	相机设备支持的硬件等级
public static final Key	INFO_VERSION	关于相机设备的制造商版本信息，例如网络服务硬件、传感器等
public static final Key<Size[]>	JPEG_AVAILABLE_THUMBNAIL_SIZES	相机设备支持的 JPEG 格式缩略图大小列表，用于 android.jpeg.thumbnailSize
public static final Key<float[]>	LENS_DISTORTION	矫正系数，以纠正相机设备的径向和切向的镜头畸变
public static final Key	LENS_FACING	相机设备相对于屏幕的方向，例如后置摄像头一般是 LENS_FACING_FRONT
public static final Key<float[]>	LENS_INFO_AVAILABLE_APERTURES	相机设备支持的光圈大小列表，用于 android.lens.aperture
public static final Key<float[]>	LENS_INFO_AVAILABLE_FILTER_DENSITIES	相机设备支持的中性密度滤波值列表，用于 android.lens.filterDensity
public static final Key<float[]>	LENS_INFO_AVAILABLE_FOCAL_LENGTHS	相机设备支持的焦距列表，用于 android.lens.focalLength
public static final Key<int[]>	LENS_INFO_AVAILABLE_OPTICAL_STABILIZATION	相机设备支持的光学稳像（optical image stabilization，OIS）模式列表，用于 android.lens.opticalStabilizationMode
public static final Key	LENS_INFO_FOCUS_DISTANCE_CALIBRATION	镜头焦距校准质量
public static final Key	LENS_INFO_HYPERFOCAL_DISTANCE	镜头的超焦距
public static final Key	LENS_INFO_MINIMUM_FOCUS_DISTANCE	能使镜头聚焦的最短距离
public static final Key<float[]>	LENS_INTRINSIC_CALIBRATION	相机设备的内部标定参数（相机内参）
public static final Key	LENS_POSE_REFERENCE	镜头的引用位置，即用于 android.lens.poseTranslation 的起始座标
public static final Key<float[]>	LENS_POSE_ROTATION	相机设备相对于传感器座标系的方向
public static final Key<float[]>	LENS_POSE_TRANSLATION	相机光学中心位置
public static final Key<float[]>	LENS_RADIAL_DISTORTION	镜头径向畸变，在 Android 28 上已弃用，使用 android.lens.distortion 代替
public static final Key	LOGICAL_MULTI_CAMERA_SENSOR_SYNC_TYPE	物理相机间帧时间戳同步的准确性，决定了物理相机同时开始曝光的能力
public static final Key<int[]>	NOISE_REDUCTION_AVAILABLE_NOISE_REDUCTION_MODES	相机设备支持的降噪模式列表，用于 android.noiseReduction.mode
public static final Key	REPROCESS_MAX_CAPTURE_STALL	重处理捕获请求时的最大失帧（以帧为单位）
public static final Key<int[]>	REQUEST_AVAILABLE_CAPABILITIES	相机设备完全支持的功能列表
public static final Key	REQUEST_MAX_NUM_INPUT_STREAMS	相机设备能够同时支持的不同类型的输入流最大数量
public static final Key	REQUEST_MAX_NUM_OUTPUT_PROC	相机设备能够同时支持的不同处理格式的输出流最大数量（无停顿）
public static final Key	REQUEST_MAX_NUM_OUTPUT_PROC_STALLING	相机设备能够同时支持的不同处理格式的输出流最大数量（有停顿）
public static final Key	REQUEST_MAX_NUM_OUTPUT_RAW	对于任何 RAW 格式，相机设备能够同时支持的不同类型的输出流最大数量
public static final Key	REQUEST_PARTIAL_RESULT_COUNT	定义一个结果将由多少个子结构组成
public static final Key	REQUEST_PIPELINE_MAX_DEPTH	指定一个帧从暴露到可使用，所经过的管道阶段数的最大值
public static final Key	SCALER_AVAILABLE_MAX_DIGITAL_ZOOM	active 区域宽高和裁剪区域宽度比值的最大值，用于 android.scaler.cropRegion
public static final Key	SCALER_CROPPING_TYPE	相机设备支持的裁剪类型，有 CENTER_ONLY 和 FREEFORM·两种
public static final Key	SCALER_STREAM_CONFIGURATION_MAP	相机设备支持的可用流的配置，包括最小帧间隔、不同格式、大小组合的失帧时长
public static final Key<int[]>	SENSOR_AVAILABLE_TEST_PATTERN_MODES	相机设备支持的测试模式列表，用于 android.sensor.testPatternMode
public static final Key	SENSOR_BLACK_LEVEL_PATTERN	每个彩色滤光片排列(CFA)镶嵌通道的固定黑色电平偏移量
public static final Key	SENSOR_CALIBRATION_TRANSFORM1	从参考传感器颜色空间映射到实际设备传感器颜色空间的每个设备校准转换矩阵
public static final Key	SENSOR_CALIBRATION_TRANSFORM2	从参考传感器颜色空间映射到实际设备传感器颜色空间(这是原始缓冲区数据的颜色空间)的每个设备校准转换矩阵
public static final Key	SENSOR_COLOR_TRANSFORM1	将颜色值从CIE XYZ颜色空间转换为参考传感器颜色空间的矩阵
public static final Key	SENSOR_COLOR_TRANSFORM2	将颜色值从CIE XYZ颜色空间转换为参考传感器颜色空间的矩阵
public static final Key	SENSOR_FORWARD_MATRIX1	一个矩阵，将白平衡摄像机颜色从参考传感器颜色空间转换为带有D50白点的CIE XYZ颜色空间
public static final Key	SENSOR_FORWARD_MATRIX2	一个矩阵，将白平衡摄像机颜色从参考传感器颜色空间转换为带有D50白点的CIE XYZ颜色空间
public static final Key	SENSOR_INFO_ACTIVE_ARRAY_SIZE	经过几何畸变校正后，图像传感器对应于活动像素的面积
public static final Key	SENSOR_INFO_COLOR_FILTER_ARRANGEMENT	传感器上颜色滤波器的排列，按读取顺序，表示传感器左上2x2部分的颜色
public static final Key<Range>	SENSOR_INFO_EXPOSURE_TIME_RANGE	相机设备支持的图片曝光时间范围，用于 android.sensor.exposureTime
public static final Key	SENSOR_INFO_LENS_SHADING_APPLIED	相机设备输出的原始图像是否受镜头阴影校正影响
public static final Key	SENSOR_INFO_MAX_FRAME_DURATION	相机设备支持的最大的帧间隔时间，用于 android.sensor.frameDuration
public static final Key	SENSOR_INFO_PHYSICAL_SIZE	完整像素数列的物理尺寸
public static final Key	SENSOR_INFO_PIXEL_ARRAY_SIZE	完整像素数列的尺寸，可能包括黑色校准像素
public static final Key	SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE	在应用任何几何畸变校正之前，与活动像素相对应的图像传感器的面积
public static final Key<Range>	SENSOR_INFO_SENSITIVITY_RANGE	相机设备支持的敏感度范围，用于 android.sensor.sensitivity
public static final Key	SENSOR_INFO_TIMESTAMP_SOURCE	传感器开始捕捉的时间戳的时间基础
public static final Key	SENSOR_INFO_WHITE_LEVEL	传感器最大的 raw 值输出
public static final Key	SENSOR_MAX_ANALOG_SENSITIVITY	纯粹通过模拟增益实现的最大敏感度
public static final Key<Rect[]>	SENSOR_OPTICAL_BLACK_REGIONS	表示传感器光学屏蔽的黑色像素区域的不相交矩形列表
public static final Key	SENSOR_ORIENTATION	使输出图像在设备屏幕上以本机方向垂直，顺时针方向旋转的角度
public static final Key	SENSOR_REFERENCE_ILLUMINANT1	当计算 android.sensor.colorTransform1, android.sensor.calibrationTransform1 和 android.sensor.forwardMatrix1 矩阵时，作为场景光源的标准参考光源
public static final Key	SENSOR_REFERENCE_ILLUMINANT2	当计算 android.sensor.colorTransform2, android.sensor.calibrationTransform2 和 android.sensor.forwardMatrix2 矩阵时，作为场景光源的标准参考光源
public static final Key<int[]>	SHADING_AVAILABLE_MODES	相机设备支持的镜头应用模式列表，用于 android.shading.mode
public static final Key<int[]>	STATISTICS_INFO_AVAILABLE_FACE_DETECT_MODES	相机设备支持的人脸检测模式列表，用于 android.statistics.faceDetectMode
public static final Key<boolean[]>	STATISTICS_INFO_AVAILABLE_HOT_PIXEL_MAP_MODES	相机设备支持的热像素映射输出模式列表，用于 android.statistics.hotPixelMapMode
public static final Key<int[]>	STATISTICS_INFO_AVAILABLE_LENS_SHADING_MAP_MODES	相机设备支持的镜头阴影映射输出模式列表，用于 android.statistics.lensShadingMapMode
public static final Key<int[]>	STATISTICS_INFO_AVAILABLE_OIS_DATA_MODES	相机设备支持
public static final Key	STATISTICS_INFO_MAX_FACE_COUNT	同时能够检测的人脸数的最大值
public static final Key	SYNC_MAX_LATENCY	请求(与前一个请求不同)提交后以及结果状态同步之前可能出现的最大帧数
public static final Key<int[]>	TONEMAP_AVAILABLE_TONE_MAP_MODES	相机设备支持的图像增强映射模式列表，用于 android.tonemap.mode
public static final Key	TONEMAP_MAX_CURVE_POINTS	图像增强映射曲线支持的最大点的数量，用于 android.tonemap.curve