Android Camera2 CameraCharacteristics API 详解

一、CameraCharacteristics概述

描述 CameraDevice 的属性。
这些属性对于给定的 CameraDevice 是固定的，并且可以通过 CameraManager 接口使用 CameraManager.getCameraCharacteristics 进行查询。
当由不持有 CAMERA 权限的客户端获取时，不包括某些元数据值。 需要权限的密钥列表由 getKeysNeedingPermission 给出。
CameraCharacteristics 对象是不可变的。

二、方法

/**

Return the device state listener for this Camera characteristics instance

*/

CameraManager.DeviceStateListener getDeviceStateListener()

/**

覆盖属性值
检查在某些特定情况下是否需要覆盖给定的属性值。
Param：
key – 要覆盖的特征字段。
Return：
被重写属性的值，如果该属性不需要重写，则为 null。

*/

@Nullable
private  T overrideProperty(Key key)

/**

获取相机特征字段值。
字段定义可以在 CameraCharacteristics 中找到。
多次查询同一键的值将返回与前一次查询的值相等的值。
Param：
key – 要读取的特征字段。
Return：
该键的值，如果未设置该字段则为 null。
Throw：
IllegalArgumentException – 如果密钥无效

*/

@Nullable
public  T get(Key key)

/**

返回此映射中包含的键的列表。
返回的列表不可修改，因此任何修改它的尝试都会抛出 UnsupportedOperationException。
通过 #get 从此列表中的键检索到的所有值都保证为非空。 每个键仅在列表中列出一次。 键的顺序未定义。

*/

@NonNull
@Override
public List> getKeys()

/**

返回 getKeys 返回的列表的子集，其中包含需要相机客户端获取 android.Manifest.permission.CAMERA 权限的所有密钥。
如果应用程序在未持有 android.Manifest.permission.CAMERA 权限的情况下调用 CameraManager.getCameraCharacteristics，则此列表中的所有键将不可用，并且调用 get 将为这些键返回 null。 如果应用程序获得 android.Manifest.permission.CAMERA 权限，则调用后续 CameraManager.getCameraCharacteristics 中的 CameraCharacteristics 将具有可用的密钥。
返回的列表不可修改，因此任何修改它的尝试都会抛出 UnsupportedOperationException。
每个键仅在列表中列出一次。 键的顺序未定义。
Return：
需要 android.Manifest.permission.CAMERA 权限的相机特征键列表。 如果当前不存在需要额外权限的密钥，则该列表可以为空。

*/

public @NonNull List> getKeysNeedingPermission() 

/**

类似的逻辑也可用于其他用例。
对推荐的流配置的支持是可选的。 如果没有针对特定用例的建议配置，请参阅 SCALER_STREAM_CONFIGURATION_MAP 以获取详尽的可用列表。
Param：
usecase – 用例 ID。
Return：
有效的RecommendedStreamConfigurationMap，如果相机设备没有针对此用例的任何建议或推荐的配置无效，则为null。
Throw：
IllegalArgumentException – 如果用例参数无效。

*/

public @Nullable RecommendedStreamConfigurationMap getRecommendedStreamConfigurationMap

/**

返回相机设备可以作为捕获会话初始化的一部分传递的 getAvailableCaptureRequestKeys 键的子集。
此列表包含难以按帧应用的关键点，并且在捕获会话生命周期期间修改时可能会导致意外延迟。 典型示例包括需要耗时的硬件重新配置或内部相机管道更改的参数。 出于性能原因，我们建议客户端将其初始值作为 SessionConfiguration.setSessionParameters 的一部分传递。 启用相机捕获会话后，还建议避免更改 SessionConfiguration.setSessionParameters 中设置的初始值。 对会话参数的控制仍然可以在捕获请求中进行，但客户端应该意识到并预期在其应用程序期间会出现延迟。 示例使用场景可能如下所示：
摄像头客户端首先通过 getAvailableSessionKeys 查询会话参数密钥列表。
在触发捕获会话创建序列之前，必须使用与特定用例匹配的适当模板通过 CameraDevice.createCaptureRequest 构建捕获请求。
客户端应检查会话参数列表，并检查列出的某些键是否与他们打算在第一个捕获请求中修改的参数匹配。
如果没有这样的匹配，则可以将捕获请求不加修改地传递给 SessionConfiguration.setSessionParameters。
如果确实存在匹配项，客户端应更新相应的值并将请求传递给 SessionConfiguration.setSessionParameters。
捕获会话初始化完成后，会话参数密钥列表可以继续作为发布或更新进一步请求时的参考。 如上所述，理想情况下应避免对会话参数进行进一步更改，如果需要更新，但客户端可能会在参数切换期间出现延迟/故障。
返回的列表不可修改，因此任何修改它的尝试都会抛出 UnsupportedOperationException。
每个键仅在列表中列出一次。 键的顺序未定义。
Return：
在捕获会话初始化期间可以传递的密钥列表。 如果相机设备不支持此类键，则列表可以为空。

*/

public List> getAvailableSessionKeys()

/**

返回 getAvailableCaptureRequestKeys 键的子集，可以为支持逻辑多摄像头的物理设备覆盖该子集。
这是 android.request.availableRequestKeys 的子集，其中包含可以使用 CaptureRequest.Builder.setPhysicalCameraKey 覆盖的键列表。 可以通过调用CaptureRequest.Builder.getPhysicalCameraKey来获取该请求密钥各自的值。 包含单个物理设备请求的捕获请求必须通过 CameraDevice.createCaptureRequest(int, Set) 构建。
返回的列表不可修改，因此任何修改它的尝试都会抛出 UnsupportedOperationException。
每个键仅在列表中列出一次。 键的顺序未定义。
返回：
可以在各个物理设备请求中覆盖的键列表。 如果相机设备不支持此类键，则列表可以为空。

*/

public List> getAvailablePhysicalCameraRequestKeys() 

/**

返回此 CameraDevice 支持的键列表，以便使用 CaptureRequest 进行查询。
返回的列表不可修改，因此任何修改它的尝试都会抛出 UnsupportedOperationException。
每个键仅在列表中列出一次。 键的顺序未定义。
请注意，没有 getAvailableCameraCharacteristicsKeys() - 请使用 getKeys() 代替。
Return：
此 CameraDevice 支持的用于 CaptureRequest 的键列表。

*/

@NonNull
public List> getAvailableCaptureRequestKeys() 

/**

返回此 CameraDevice 支持的键列表，以便使用 CaptureResult 进行查询。
返回的列表不可修改，因此任何修改它的尝试都会抛出 UnsupportedOperationException。
每个键仅在列表中列出一次。 键的顺序未定义。
请注意，没有 getAvailableCameraCharacteristicsKeys() - 请使用 getKeys() 代替。
Return：
此 CameraDevice 支持的用于 CaptureResults 的键列表。

*/

@NonNull
public List> getAvailableCaptureResultKeys()

/**

返回由该逻辑 CameraDevice 组成的物理相机 ID 集。
如果相机设备具有 REQUEST_AVAILABLE_CAPABILITIES_LOGICAL_MULTI_CAMERA 功能，则该相机设备是逻辑相机。 如果相机设备不具备该功能，则返回值将为空集。
在API级别29之前，所有返回的ID都保证由CameraManager.getCameraIdList返回，并且可以直接由CameraManager.openCamera打开。 从API级别29开始，对于每个返回的ID，如果它也是由CameraManager.getCameraIdList返回的，则它可以被CameraManager.openCamera用作独立相机。 否则，摄像机ID只能作为当前逻辑摄像机的一部分。
返回的集合不可修改，因此任何修改它的尝试都会抛出 UnsupportedOperationException。
Return：
该逻辑相机设备的物理相机 ID 集。

*/

@NonNull
public Set getPhysicalCameraIds()